IP-MCP

English · 日本語

Claude에서 자연어로 일본 특허를 조회하세요. IP-MCP는 일본 특허청의 공식 "특허 정보 검색 API"를 MCP 서버로 감싸서, Claude Desktop, Claude Code, iPhone Claude가 특허 번호를 변환하고, 등록 상태를 확인하고, 인용 문헌을 가져오고, 5개국 특허 패밀리를 탐색할 수 있게 합니다 — 공식 API 도구 12개와 의도적으로 격리된 키워드 검색 도구 1개.

30초 만에 Claude에게 물어볼 수 있는 것

사용자: "JP-2010-228687의 등록 상태와 선행 기술을 알려줘."

Claude (내부적으로):

1. jpo_convert_patent_number → 출원 번호 2009080841

2. jpo_get_patent_registration → 등록 5094774, Hitachi Ltd., 2029-03-30 만료, 유효

3. jpo_get_patent_citations → 선행 기술 인용 20건

답변: "열차 제어 지상 장치 및 시스템"(Hitachi Ltd.)은 2012-09-28에 JP5094774로 등록되었으며, 현재 효력이 유지 중이고, 2029-03-30에 만료됩니다. 조사 보고서와 거절 이유에서 선행 기술 인용 20건, 모두 특허 문헌(NPL 없음)…

키워드 검색은 별도의 도구(external_search_patents_by_keyword, Google Patents XHR)로 분리되어 있습니다. LLM이 공식 API에서 비공식 소스로 우발적으로 폴백할 수 없습니다 — 모든 응답에는 명시적인 source 필드가 포함됩니다.

Related MCP server: MCP-ndl-search

비교

키워드 검색을 별도 도구 카테고리로 둔 이유는?

공식 JPO API는 번호 조회 전용입니다 — 모든 엔드포인트는 출원 / 공개 / 등록 번호, 출원인 코드, 또는 정확히 일치하는 출원인 이름을 입력으로 받습니다. 키워드 / IPC / F-term / 날짜 범위 / 부분 이름 검색은 스펙에 존재하지 않습니다. 따라서:

• tools_official/ — 도구 이름이 jpo_*로 시작하며, 응답은 {"source": "jpo_official", …}

• tools_external/ — 도구 이름이 external_*로 시작하며, 응답은 {"source": "google_patents_unofficial", …}

• 경계 테스트가 tools_external/에서 tools_official/로의 import를 금지합니다. 조용한 폴백 없음 — 비공식 소스를 사용할지 여부는 LLM이 결정합니다.

아키텍처

flowchart LR
    User["Claude Desktop /<br/>Claude Code /<br/>iPhone Claude"]
    CF["Cloudflare<br/>(Edge TLS + Tunnel)"]
    Caddy["Caddy<br/>(CF Origin Cert)"]

    User -->|"HTTPS + OAuth"| CF
    CF -->|"outbound from home<br/>via cloudflared"| Caddy
    Caddy -->|"http+SSE"| MCP

    subgraph Docker["Docker container (Python 3.12 + FastMCP)"]
      MCP["MCP server<br/>:8765"]
      Official["tools_official/<br/>(jpo_* 12 tools)"]
      External["tools_external/<br/>(external_* 1 tool)"]
      OAuth["OAuth 2.1<br/>SQLite-backed"]
      MCP --> Official
      MCP --> External
      MCP -.->|"persisted"| OAuth
    end

    Official -->|"OAuth2 password grant"| JPO[("JPO Patent API")]
    External -->|"3s spacing + 503 backoff"| GP[("Google Patents XHR")]

    classDef boundary stroke-dasharray: 5 5
    class External,GP boundary

핵심 설계 규칙:

• tools_official/(공식 JPO)와 tools_external/(비공식 Google Patents)은 코드 계층, 호출 지점, 로거 수준에서 완전히 분리됩니다. 경계 테스트가 tools_external/에서 tools_official/로의 import를 차단합니다.

• 재시도는 동일한 데이터 소스 내에서만 허용됩니다 (401 → 토큰 갱신, 303 → 지수 백오프). 실패 시 소스 간 자동 폴백은 금지됩니다 — LLM이 결정합니다.

• 모든 응답에는 {"source": "jpo_official"} 또는 {"source": "google_patents_unofficial"}가 포함됩니다.

빠른 시작

로컬 개발

cp .env.example .env          # Fill in JPO_USERNAME / JPO_PASSWORD
chmod 600 .env
docker compose up -d --build

LAN 배포 (인증 없음)

docker-compose.override.yml을 만들어 LAN 인터페이스에 바인딩하세요 (리포지토리에는 docker-compose.override.yml.example이 포함되어 있습니다):

services:
  ip-mcp:
    ports:
      - "YOUR_SERVER_IP:8765:8765"   # your LAN IP

Claude Desktop / Code 설정:

{
  "mcpServers": {
    "ip-mcp": {
      "transport": { "type": "sse", "url": "http://YOUR_SERVER_IP:8765/sse" }
    }
  }
}

Codex CLI의 직접 HTTP MCP(codex mcp add --url)는 Streamable HTTP를 기대하므로, Codex에서 직접 사용할 때는 /mcp 경로를 등록하세요:

CODEX_HOME=/path/to/codex-home codex mcp add ip-mcp --url https://your-host.example.com/mcp
CODEX_HOME=/path/to/codex-home codex mcp login ip-mcp

SSE 클라이언트는 /sse를 등록합니다. 동일한 공개 서버에서 Codex 직접 HTTP와 SSE 클라이언트를 모두 서비스하려면 MCP_TRANSPORT=both로 시작하여 동일한 OAuth 구성 아래 /mcp와 /sse를 모두 노출하세요. 단일 클라이언트의 경우 MCP_TRANSPORT=sse(기본값) 또는 MCP_TRANSPORT=streamable-http도 작동합니다.

iPhone Claude / claude.ai (공개, OAuth 2.1)

공개 노출을 위한 권장 구성은 Cloudflare Tunnel + Caddy(CF Origin Cert)입니다 — cloudflared가 홈 네트워크에서 CF 엣지로 아웃바운드 연결을 하므로 라우터 포트 포워딩이 필요 없고 헤어핀 NAT 문제도 없습니다. Let's Encrypt + 직접 443 포트를 사용하는 기존의 리버스 프록시 방식도 작동합니다. 어느 쪽이든 MCP_OAUTH_MASTER_PASSWORD + MCP_OAUTH_ISSUER_URL을 설정하여 OAuth 2.1(DCR + PKCE + 마스터 비밀번호 동의)을 활성화하세요. 발급된 클라이언트 토큰은 SQLite에 유지되어 컨테이너 재시작 후에도 보존됩니다.

MCP_OAUTH_MASTER_PASSWORD=<24+ chars random>
MCP_OAUTH_ISSUER_URL=https://your-host.example.com
# optional: MCP_OAUTH_DB_PATH=/app/data/oauth.db

전체 배포 + 운영 세부 사항은 PLAN.md §9-§10 및 OPERATIONS.md를 참조하세요 (현재 일본어).

도구 목록

응답: {"ok": true, "source": "jpo_official", "data": {…}, "remaining_today": "…"}

응답: {"ok": true, "source": "google_patents_unofficial", "data": {…}}

공식 API에는 키워드 검색이 없기 때문에(번호 조회 전용) 격리되어 있습니다. 실패 시 {"ok": false, "kind": "search_unavailable"}을 반환하며 공식 도구로 폴백하지 않습니다.

요청 한도 (운영)

공식 JPO API는 자체 제한 조절 책임을 운영자에게 위임합니다:

• 분당 요청 수: /api/patent/*는 10 req/min, /opdapi/*는 5 req/min (OPD는 별도 버킷으로 별도 계산).

• 일일 할당량: 엔드포인트당 30–800/일 (국가 API 할당량은 2026년 3월에 두 배로 증가). 권위 있는 실시간 카운터는 모든 응답에 포함되는 result.remainAccessCount입니다.

• jpo_fetch_full_record는 4개의 공식 엔드포인트에 병렬로 분기하므로, 한 번의 호출이 4개의 서로 다른 일일 할당량에서 각각 1단위를 소비합니다 (동일한 할당량에서 4단위가 아님). 병목은 가장 낮은 할당량입니다.

도구-엔드포인트 매핑 및 운영 임계값은 OPERATIONS.md §JPO API レート制約とクォータ (일본어)를 참조하세요.

문서

• 📐 PLAN.md — 설계 계획 (아키텍처, 전체 도구 목록, 단계별 계획) [JP]

• 🤖 CLAUDE.md — Claude Code 가이드 (양보할 수 없는 설계 규칙, JPO API 주의사항) [JP]

• 🔧 OPERATIONS.md — 운영 런북 (액세스 로그 요약, 마스터 비밀번호 교체, 문제 해결) [JP]

docker-compose.yml의 포트 바인딩은 기본적으로 127.0.0.1:8765(동일 머신 전용)입니다. LAN에 노출하려면 별도의 docker-compose.override.yml(이미 gitignore됨)을 만들어 재정의하세요.

라이선스

MIT — LICENSE 참조.