gp-cli — Google Patents CLI

gp-cli는 특허 검토, 청구항 분석, AI 코딩 에이전트 워크플로우를 위한 빠른 Google Patents CLI입니다.

주요 기능:

특허 메타데이터, 청구항, 설명, 인용, 패밀리 출원 정보를 구조화해 조회
특허 PDF와 고해상도 도면 이미지 다운로드
특허번호 목록 일괄 처리 및 자동화용 요청 지연 적용
입력 특허를 패밀리별로 그룹핑하고 이미 확인된 패밀리 멤버 fetch 스킵
Claude Code, Codex CLI, Gemini CLI 등 에이전트 런타임용 MCP 도구 제공

터미널 사용에 맞춰 설계되었습니다. JSON/TSV/text 출력이 깔끔하게 분리되고, 스크립트 친화적인 exit code를 제공하며, headless browser가 필요 없습니다.

English documentation: README.md

설치

macOS

터미널(Terminal)을 열고 아래 명령어를 복사·붙여넣기 하세요:

curl -fsSL https://raw.githubusercontent.com/noaa/patent-cli/main/install.sh | sh

설치 후 터미널을 새로 열면 gp-cli 명령을 바로 사용할 수 있습니다.

Windows

방법 A — PowerShell (시작 메뉴 → "PowerShell" 검색):

irm https://raw.githubusercontent.com/noaa/patent-cli/main/install.ps1 | iex

방법 B — 명령 프롬프트(CMD) (시작 메뉴 → "cmd" 검색):

curl -fsSL https://raw.githubusercontent.com/noaa/patent-cli/main/install.bat -o "%TEMP%\gp-cli-install.bat" && "%TEMP%\gp-cli-install.bat"

Windows 10 build 1803 이상이 필요합니다 (curl·tar 내장).

설치 후 터미널을 새로 열면 gp-cli 명령을 바로 사용할 수 있습니다.

수동 설치 (직접 다운로드)

자동 설치가 안 될 경우 Releases 페이지에서 직접 다운로드하세요:

OS	파일
macOS (M1/M2/M3)	`gp-cli-darwin-arm64.tar.gz`
macOS (Intel)	`gp-cli-darwin-amd64.tar.gz`
Windows	`gp-cli-windows-amd64.exe.zip`
Linux	`gp-cli-linux-amd64.tar.gz`

압축 해제 후 gp-cli(또는 gp-cli.exe)를 원하는 폴더에 넣으면 됩니다.

소스 코드로 직접 빌드

Go 1.21+가 설치되어 있어야 합니다.

git clone https://github.com/noaa/patent-cli.git
cd patent-cli
go build -o gp-cli ./cmd/gp-cli/

빌드된 바이너리를 PATH에 있는 디렉토리로 이동합니다:

# macOS / Linux
mv gp-cli ~/.local/bin/

# Windows (PowerShell)
Move-Item gp-cli.exe $env:LOCALAPPDATA\gp-cli\gp-cli.exe

Claude Code 플러그인

왜 patent-cli인가? 순수 HTTP 요청 방식으로 Headless 브라우저 오버헤드가 없습니다. MCP 호출 1회로 결과를 직접 반환 — 브라우저 기반 플러그인 대비 응답속도가 현저히 빠릅니다.

설치

# 1. gp-cli 바이너리 설치 (아직 설치하지 않은 경우)
curl -fsSL https://github.com/noaa/patent-cli/releases/latest/download/install.sh | sh

# 2. 마켓플레이스 등록 (플러그인 설치 전 필수)
claude plugin marketplace add noaa/patent-cli

# 3. Claude Code 플러그인 설치
claude plugin install patent-cli

제공되는 스킬 및 MCP 툴

스킬	MCP 툴	설명
`/patent-lookup`	`patent_lookup`	특허번호로 특허 상세 정보 조회
`/patent-fields`	`patent_fields`	사용 가능한 필드 목록 조회

Codex 플러그인

# 1. gp-cli 바이너리 설치 (아직 설치하지 않은 경우)
curl -fsSL https://github.com/noaa/patent-cli/releases/latest/download/install.sh | sh

# 2. 저장소 클론
git clone https://github.com/noaa/patent-cli.git
cd patent-cli

# 3. 로컬 Codex marketplace 등록
codex plugin marketplace add ./codex-marketplace

# 4. 해당 marketplace에서 플러그인 설치
codex plugin add patent-cli@patent-cli-local

# 5. 설치 확인
codex plugin list

Claude Code 플러그인과 동일한 스킬 및 MCP 툴을 제공합니다. Codex CLI에서 설치하면 Codex 데스크탑 앱에서도 자동으로 인식됩니다.

로컬 개발 중에는 codex-plugin/ 아래 파일을 수정한 뒤 다시 설치합니다:

codex plugin add patent-cli@patent-cli-local

재설치 후에는 새 Codex thread를 시작해야 업데이트된 스킬과 MCP 설정이 로드됩니다.

Antigravity 플러그인

# 1. gp-cli 바이너리 설치 (아직 설치하지 않은 경우)
curl -fsSL https://github.com/noaa/patent-cli/releases/latest/download/install.sh | sh

# 2. ~/.config/antigravity/settings.json의 "mcpServers"에 다음을 추가:
#   "patent-cli": { "command": "gp-cli", "args": ["mcp"], "transport": "stdio" }

# 3. 스킬 파일을 로컬 스킬 디렉터리에 복사
cp -r antigravity-plugin/skills/* ~/.config/antigravity/skills/

Claude Desktop 확장

.mcpb 번들로 드래그 앤 드롭 설치 — 바이너리가 번들 안에 포함되어 있어 사전 설치가 필요 없습니다.

# GitHub Releases에서 플랫폼에 맞는 .mcpb 파일을 다운로드한 후:
# Claude Desktop → 설정 → 확장 → patent-cli-<플랫폼>.mcpb 파일을 드래그 앤 드롭

릴리스별 .mcpb 에셋:

파일	플랫폼
`patent-cli-darwin-arm64.mcpb`	macOS Apple Silicon
`patent-cli-darwin-amd64.mcpb`	macOS Intel
`patent-cli-windows-amd64.mcpb`	Windows x64

사용법

특허 메타데이터 조회

# JSON 형식 (기본값)
gp-cli lookup US12514139B2

# 사람이 읽기 편한 텍스트 형식
gp-cli lookup US12514139B2 --format text

# 특정 필드만 출력
gp-cli lookup US12514139B2 --fields title,assignee,filing_date

# 단일 필드 값만 출력 (plain text)
gp-cli lookup US12514139B2 --field title

# JSON 한 줄 출력 (들여쓰기 없음)
gp-cli lookup US12514139B2 --minify

# 진행 메시지 억제 (스크립트에서 유용)
gp-cli lookup US12514139B2 --quiet

# 비영어권 특허 기계번역 영문으로 조회
gp-cli lookup KR102355140B1 --language en

# 구조화된 청구항·설명 (opt-in 필드)
gp-cli lookup US12514139B2 --fields claims_structured,description_structured

# 파일로 저장 (stdout 출력 억제)
gp-cli lookup US12514139B2 --output-dir ./output

# 단일 필드를 파일로 저장
gp-cli lookup US12514139B2 --field claims --output-dir ./output

PDF 다운로드

gp-cli download US12514139B2
gp-cli download US12514139B2 --output-dir ./pdfs

도면 이미지 다운로드

gp-cli images US12514139B2
gp-cli images US12514139B2 --output-dir ./figures
# US12514139B2_fig01.png, US12514139B2_fig02.png, ... 형태로 저장됨

특허 패밀리별 그룹핑

# 명령행에 특허번호 직접 지정
gp-cli family-group US8725880B2 US8704863B2 US9735861B2

# 파일에서 특허번호 읽기
gp-cli family-group --input-file patents.txt --format text

# 스프레드시트용 TSV 출력
gp-cli family-group --input-file patents.txt --format tsv --output-dir ./groups

family-group은 각 특허의 family_applications를 조회해 같은 패밀리에 속한 입력 특허들을 같은 그룹으로 묶습니다. 이후 입력 특허가 이미 조회된 패밀리의 멤버로 확인되면 해당 특허 fetch를 건너뛰어 Google Patents 요청 수를 줄입니다. fetch 사이에는 1000-1500 ms 랜덤 지연이 자동 적용되며, --delay MS로 명시 지연시간을 지정할 수 있습니다.

사용 가능한 필드 목록

gp-cli fields

출력 형식

옵션	설명
`--format json`	JSON (기본값) — `lookup`은 `{"ok": true, "results": {...}}`, `family-group`은 `{"ok": true, "groups": [...], "summary": {...}}` 형태
`--format text`	레이블 + 값 텍스트
`--format tsv`	탭 구분 (Excel 붙여넣기용)
`--output-dir DIR`	파일로 저장; stdout 출력 억제
`--no-header`	TSV 헤더 행 생략 (루프에서 행 추가 시 유용)
`--minify`	JSON 한 줄 출력 (들여쓰기 없음)

전역 플래그

플래그	설명
`--quiet`, `-q`	stderr 진행 메시지 억제 (스크립트용)
`--minify`	JSON 한 줄 출력 (들여쓰기 없음)
`--verbose`, `-v`	디버그 로그를 stderr에 출력
`--language LANG`	Google 기계번역 페이지로 조회 (예: `en`). 비영어권 특허 영문 조회에 유용.

에러 처리

에러는 stderr에 구조화된 JSON으로 출력되며, 유형별 exit code와 함께 종료됩니다.

{
  "ok": false,
  "error": {
    "type": "NOT_FOUND",
    "message": "patent not found: US99999999X1"
  }
}

Exit code	의미
`0`	성공
`1`	일반 오류
`4`	특허 미발견
`6`	서버 오류 (봇 차단, 5xx)

에러가 stderr로 분리되므로 stdout은 항상 순수한 데이터입니다. 파일 리디렉션이나 jq 파이프라인에서 에러 JSON 혼입 걱정 없이 사용할 수 있습니다.

# 안전: TSV 데이터만 파일에 저장, 에러는 터미널에 표시
while IFS= read -r num; do
  gp-cli lookup "$num" --format tsv --quiet
done < list.txt > results.tsv

스크립트 & 파이프라인

헤더 중복 없이 TSV 일괄 생성

first=1
while IFS= read -r num; do
  if [ $first -eq 1 ]; then
    gp-cli lookup "$num" --fields publication_number,title,assignee --format tsv --quiet --delay 1000
    first=0
  else
    gp-cli lookup "$num" --fields publication_number,title,assignee --format tsv --quiet --no-header --delay 1000
  fi
done < patent_list.txt > summary.tsv

`jq`로 인용 특허번호 추출

gp-cli lookup US8725880B2 --field backward_citations --quiet \
  | jq -r '.[].publication_number'

독립항만 필터링

gp-cli lookup US12514139B2 --fields claims_structured --quiet \
  | jq '[.results.claims_structured[] | select(.type == "independent")]'

청구항 1과 직접 종속항만 추출

gp-cli lookup US12514139B2 --fields claims_structured --quiet \
  | jq '[.results.claims_structured[] | select(.number == "1" or (.depends_on // [] | any(. == "1")))]'

여러 특허 도면 일괄 다운로드 (파일명 충돌 없음)

# US11125686B2_fig01.png, EP3025568B1_fig01.png, ... 형태로 저장
for num in US11125686B2 EP3025568B1; do
  gp-cli images "$num" --output-dir ./figures --quiet --delay 1000
done

특허 목록을 패밀리별로 그룹핑

gp-cli family-group --input-file patent_list.txt --format tsv --quiet > family_groups.tsv

JSON 출력에는 fetch 스킵 최적화 확인용 summary.fetch_count 값이 포함됩니다:

gp-cli family-group US8725880B2 US8704863B2 US9735861B2 --minify --quiet \
  | jq '.summary.fetch_count'

Opt-in 구조화 필드

기본 출력에 포함되지 않으며, --field 또는 --fields로 명시적으로 요청해야 합니다:

필드	스키마
`claims_structured`	`{"number": "1", "type": "independent"\|"dependent", "depends_on": ["N"], "text": "…"}`
`description_structured`	`{"number": "1", "id": "…", "text": "…"}`

type과 depends_on은 HTML <claim-ref> 태그를 통해 US/EP 특허에서만 감지됩니다. 번역 페이지(--language en)나 KR/JP/CN 원문에서는 이 마크업이 없어 해당 필드가 생략됩니다.

gp-cli lookup US12514139B2 --fields claims_structured
gp-cli lookup US12514139B2 --fields claims_structured,description_structured
gp-cli fields   # opt-in 필드 포함 전체 필드 목록 확인

데이터 품질 경고 (`_warnings`)

claims_structured를 요청하면 JSON 엔벨로프의 ok, results 옆에 _warnings 배열이 추가될 수 있습니다. 문제가 없으면 키 자체가 생략됩니다.

{
  "ok": true,
  "results": { "claims_structured": [...] },
  "_warnings": [
    {
      "field": "claims_structured",
      "code": "TRANSLATED_PAGE_NO_TYPE_INFO",
      "message": "Claim type and dependency data unavailable; page was served as a machine translation"
    },
    {
      "field": "claims_structured",
      "code": "SUSPICIOUSLY_SHORT_CLAIM_TEXT",
      "message": "Claim(s) 1 have text ≤ 20 chars; likely translation artifacts — verify against source"
    }
  ]
}

경고 코드	의미
`TRANSLATED_PAGE_NO_TYPE_INFO`	모든 청구항에 `type`이 없음 — 기계번역 페이지로 `depends_on`도 없음
`SUSPICIOUSLY_SHORT_CLAIM_TEXT`	텍스트가 20자 이하인 청구항 존재 — 번역 아티팩트일 가능성 높음

설정 (프록시 / CA 인증서)

회사 내부망에서 프록시를 사용하는 경우:

gp-cli configure

설정 파일 위치: macOS ~/Library/Application Support/patent-cli/config.toml, Linux ~/.config/patent-cli/config.toml

[proxy]
https = "http://proxy.corp:8080"
http  = "http://proxy.corp:8080"

[ssl]
ca_bundle = "/path/to/ca.pem"

[request]
delay_ms = 500   # 요청마다 대기 시간(ms) — 루프에서 봇 차단 방지용

버전 확인 & 업데이트

gp-cli --version
gp-cli update           # 최신 버전으로 자동 업데이트
gp-cli update --check   # 버전 정보만 확인 (업데이트 미진행)

gp-cli update는 gp-cli configure에서 설정한 프록시·CA 인증서 설정을 자동으로 사용합니다. 회사 내부망에서도 별도 조치 없이 업데이트 명령이 동작합니다.

제거 (Uninstall)

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/noaa/patent-cli/main/uninstall.sh | sh

바이너리(~/.local/bin/gp-cli)와 설정 디렉터리를 삭제합니다. ~/.zshrc 또는 ~/.bashrc의 PATH 항목은 안내 메시지를 참고해 직접 제거하세요.

Windows

PowerShell:

irm https://raw.githubusercontent.com/noaa/patent-cli/main/uninstall.ps1 | iex

명령 프롬프트(CMD):

curl -fsSL https://raw.githubusercontent.com/noaa/patent-cli/main/uninstall.bat -o "%TEMP%\gp-cli-uninstall.bat" && "%TEMP%\gp-cli-uninstall.bat"

두 Windows 스크립트 모두 바이너리(%LOCALAPPDATA%\gp-cli\gp-cli.exe), 설정 디렉터리(%APPDATA%\patent-cli), PATH 레지스트리 항목을 자동으로 제거합니다.

개발

# 빌드
go build ./...
go build -o gp-cli ./cmd/gp-cli/

# 유닛 테스트 (네트워크 불필요)
go test ./internal/fetcher/ ./internal/formatter/ ./internal/parser/ -v

# 통합 테스트 (실제 Google Patents 접속 — 약 15초)
go test -tags integration ./tests/integration/ -v -timeout 300s

# MCP 서버 실행 (stdio — 입력 대기 상태면 정상)
gp-cli mcp

유닛 테스트: 특허번호 정규화, 봇 차단 감지, JSON/text/TSV 렌더링, 구조화 필드 경고, US/번역 청구항 및 설명 HTML 파싱 커버.

통합 테스트: 실제 특허를 대상으로 국가별(US/EP/KR/JP/CN/GB/DE/AU/BR/MX/TW/WO) 실행. NOT_FOUND, --minify, --fields, --language, claims_structured / description_structured 케이스 포함.

FilesExpand file tree

README.ko.md

Latest commit

History

README.ko.md

File metadata and controls

gp-cli — Google Patents CLI

설치

macOS

Windows

수동 설치 (직접 다운로드)

소스 코드로 직접 빌드

Claude Code 플러그인

설치

제공되는 스킬 및 MCP 툴

Codex 플러그인

Antigravity 플러그인

Claude Desktop 확장

사용법

특허 메타데이터 조회

PDF 다운로드

도면 이미지 다운로드

특허 패밀리별 그룹핑

사용 가능한 필드 목록

출력 형식

전역 플래그

에러 처리

스크립트 & 파이프라인

헤더 중복 없이 TSV 일괄 생성

jq로 인용 특허번호 추출

독립항만 필터링

청구항 1과 직접 종속항만 추출

여러 특허 도면 일괄 다운로드 (파일명 충돌 없음)

특허 목록을 패밀리별로 그룹핑

Opt-in 구조화 필드

데이터 품질 경고 (_warnings)

설정 (프록시 / CA 인증서)

버전 확인 & 업데이트

제거 (Uninstall)

macOS / Linux

Windows

개발

`jq`로 인용 특허번호 추출

데이터 품질 경고 (`_warnings`)