IP-MCP

English · 日本語

用自然语言从 Claude 查询日本专利。 IP-MCP 将 Japan Patent Office 的官方 “Patent Information Retrieval API” 封装为 MCP 服务器，因此 Claude Desktop、Claude Code 和 iPhone Claude 可以解析专利号、查看注册状态、获取引用文献，并遍历五局同族——12 个官方 API 工具，外加 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）在代码层级、调用点和 logger 层面完全隔离。边界测试会阻止从 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

局域网部署（无认证）

创建 docker-compose.override.yml 以绑定到你的局域网接口（仓库附带 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 边缘，因此无需路由器端口转发，hairpin 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 次/分钟，/opdapi/* 为 5 次/分钟（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]