MCP KIPRIS

MCP KIPRIS

English | 한국어 →

一个 MCP（模型上下文协议） 服务，让 Claude 等 AI 助手能够直接访问 KIPRIS——由韩国知识产权局（KIPO）运营的韩国官方专利和商标数据库。

---

为什么选择 KIPRIS？

韩国是全球专利申请量排名前 5 的国家之一。Samsung、LG、SK Hynix、Hyundai 和 POSCO 等公司每年都会申请数万项专利，所有这些专利都可以通过 KIPRIS 搜索。

这个 MCP 服务让 Claude（或任何兼容 MCP 的 AI 客户端）能够使用自然语言搜索这些专利，用户无需浏览韩语版 KIPRIS 门户网站。

典型用例：

• 申请专利前搜索现有技术
• 了解韩国科技公司的竞争情报
• 监控特定技术领域的 IPC 分类
• 为韩国市场进行商标检索

---

快速开始

前提条件： Python 3.11+，以及免费的 KIPRIS API 密钥

# 1. Clone and install
git clone https://github.com/nuri428/mcp_kipris.git
cd mcp_kipris
pip install -e .

# 2. Set your API key
export KIPRIS_API_KEY="your_api_key_here"

# 3. Run the server (stdio mode for Claude Desktop)
python -m mcp_kipris.server

然后将服务添加到 Claude Desktop——请参阅Claude Desktop 配置。

---

获取 KIPRIS API 密钥

1. 访问 https://plus.kipris.or.kr（网站为韩语，可使用浏览器翻译功能）
2. 注册免费账户
3. 在开发者门户申请 Open API 密钥
4. 非商业用途可免费使用该密钥，但每日请求次数有限额

---

速率限制

发往 KIPRIS 的请求会由进程内速率限制器进行节流，每分钟最多 60 个请求（RateLimiter 中的默认值，位于 src/mcp_kipris/kipris/rate_limiter.py）。达到上限时，请求会等待并自动重试，而不会失败——您无需进行任何操作。目前无法通过环境变量配置此限制。

这只限制此服务调用 KIPRIS 的速度；它与您在 KIPRIS 开发者门户中 API 密钥自身的每日请求限额无关。

---

功能

韩国专利搜索

工具	说明
patent_applicant_search	按申请人名称搜索专利
patent_free_search	全文关键词搜索
patent_application_number_search	按申请号搜索
patent_righter_search	按权利人名称搜索
patent_detail_search	按申请号获取专利详情。支持 fields 参数，可选择约 65 个可用字段的任意组合（书目信息、IPC、摘要、权利要求、申请人／发明人／代理人、优先权、法律状态、研发资金等）；省略该参数则返回简短的默认摘要
patent_summary_search	按申请号获取专利摘要
abstract_search	按摘要／发明概要搜索——由 @haseo-ai 贡献
ipc_search	按 IPC 分类代码搜索——由 @haseo-ai 贡献
agent_search	按专利代理人名称搜索——由 @haseo-ai 贡献
patent_advanced_search	通过 KIPRIS 的高级搜索服务按申请号搜索（与 patent_application_number_search 使用不同的 KIPRIS 接口）
patent_search	⚠️ 已弃用——已更名为 patent_advanced_search。为保持向后兼容而保留；计划在未来的主版本中移除。

商标搜索

工具	描述
trademark_search	按关键词搜索韩国商标 — 由 @haseo-ai 贡献

国际专利搜索

通过 KIPRIS 国际数据库搜索来自 13 个国家的专利：

工具	描述
foreign_patent_applicant_search	按申请人搜索外国专利
foreign_patent_application_number_search	按申请号搜索外国专利
foreign_patent_free_search	使用自由文本搜索外国专利
foreign_international_application_number_search	按 PCT 国际申请号搜索
foreign_international_open_number_search	按国际公开编号搜索

---

安装

选项 1：通过 Smithery（最简单 — 无需本地设置）

通过 Smithery marketplace 直接安装。Smithery 会处理设置并提示你输入 KIPRIS API 密钥：

npx @smithery/cli@latest mcp add greennuri/mcp-kipris

也可以访问 smithery.ai/servers/greennuri/mcp-kipris 并点击 安装。

选项 2：从 PyPI 安装

pip install mcp-kipris

选项 3：从源代码安装（开发）

git clone https://github.com/nuri428/mcp_kipris.git
cd mcp_kipris

# Option A — using uv (recommended)
pip install uv
uv sync

# Option B — using pip
pip install -e .

环境配置

# Shell export (session-scoped)
export KIPRIS_API_KEY="your_api_key_here"

# Or create a .env file at the project root
echo 'KIPRIS_API_KEY=your_api_key_here' > .env

---

运行服务

stdio 模式 — 适用于 Claude Desktop 和大多数 MCP 客户端

# via uv
uv run python -m mcp_kipris.server

# via python directly (if installed with pip install -e .)
python -m mcp_kipris.server

HTTP / SSE 模式 — 适用于基于 Web 的 MCP 客户端

uv run python -m mcp_kipris.sse_server --http --port 6274 --host 0.0.0.0

通过 mcpo 代理（stdio → HTTP 桥接）

uvx mcpo --port 6274 -- uv run python -m mcp_kipris.server

Docker

bash sse_server_build.sh

---

Claude Desktop 配置

将此代码块添加到 Claude Desktop 的 claude_desktop_config.json （在 macOS 上通常位于 ~/Library/Application Support/Claude/）：

{
  "mcpServers": {
    "kipris": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_kipris.server"],
      "cwd": "/absolute/path/to/mcp_kipris",
      "env": {
        "KIPRIS_API_KEY": "your_api_key_here"
      }
    }
  }
}

---

测试

运行测试套件

test/ 中有两类测试：

• test/unit/ — 完全模拟，无需访问网络，也不需要 KIPRIS_API_KEY。标记为 pytest.mark.unit。
• 根目录下的 test_*.py — 调用实时 KIPRIS API，需要有效的 KIPRIS_API_KEY。其中一个 pytest 可发现的用例标记为 pytest.mark.integration；其余是由 if __name__ == "__main__": 守护的独立演示脚本。

# Install
uv sync --group dev

# Unit tests only — fast, no API key needed
pytest test/unit -v

# Everything except the live-API integration test
pytest test/ -m "not integration" -v

# Full suite with coverage (what CI runs — needs KIPRIS_API_KEY)
pytest test/ -v --cov=src/mcp_kipris --cov-report=term-missing

也可以直接运行各个演示脚本：

python test/test_samsung_patents.py
python test/test_patent_keyword_search.py

检查代码和格式化

ruff check src/
ruff format src/

分发测试

发布版本打标签前，请确认软件包能够顺利构建和安装：

# 1. Build wheel and sdist
pip install build
python -m build

# 2. Smoke-test the wheel in a clean virtualenv
python -m venv /tmp/kipris-smoke
source /tmp/kipris-smoke/bin/activate
pip install dist/mcp_kipris-*.whl
python -c "import mcp_kipris; print('import OK')"
deactivate
rm -rf /tmp/kipris-smoke

# 3. Verify editable install still works
pip install -e .
pytest test/ -v

CI 矩阵

每次向 main / develop 推送或提交拉取请求时，都会在 Python 3.11 和 3.12 上运行完整流水线：

步骤	工具	说明
代码检查	ruff check	PEP 8 + 风格规则
格式化	ruff format --check	确保格式一致
测试	pytest	主要为模拟单元测试，另有一个实时 API 集成测试；需要 KIPRIS_API_KEY 密钥
覆盖率	Codecov	从 Python 3.12 的运行中上传报告

---

API 使用示例

这些示例使用 HTTP/SSE 服务模式。首先，获取会话 ID：

# Start the SSE server
uv run python -m mcp_kipris.sse_server --http --port 6274 --host 0.0.0.0

# Get a session ID
curl -N http://localhost:6274/messages/
# → event: endpoint
# → data: /messages/?session_id=<SESSION_ID>

按申请人搜索专利 — Samsung Electronics

# "삼성전자" is the Korean name for Samsung Electronics
curl -X POST "http://localhost:6274/messages/?session_id=<SESSION_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool",
    "name": "patent_applicant_search",
    "args": {
      "applicant": "삼성전자",
      "docs_count": 5,
      "desc_sort": true
    }
  }'

列出所有可用工具

curl http://localhost:6274/tools | jq .

响应格式

所有工具都会返回封装在以下结构中的 Markdown 表格：

[
  {
    "type": "text",
    "text": "| application_number | title | applicant | ...\n|---|---|---|...",
    "metadata": null
  }
]

---

参考

支持的国家/地区代码（国际搜索）

代码	国家/数据库
US	美国
EP	欧洲专利局
WO	PCT / WIPO
JP	日本
PJ	日本（英文摘要）
CP	中国
CN	中国（英文摘要）
TW	台湾（英文摘要）
RU	俄罗斯
CO	哥伦比亚
SE	瑞典
ES	西班牙
IL	以色列

排序选项

代码	排序依据
PD	公布日期
AD	申请日期
GD	注册日期
OPD	公开日期
FD	国际申请日期
FOD	国际公布日期
RD	优先权主张日期

专利状态代码

代码	状态
A	已公开
C	更正公开
F	已授权
G	更正授权
I	已失效
J	已取消
R	重新公开

---

ClaudeWork 技能

如果您使用 ClaudeWork，此服务也已打包为可直接使用的技能：

kipris_skill →

---

已知限制

已针对 KIPRIS API 实际测试了全部 17 个工具。其中 16 个工具的验证不止于“返回格式良好的输出”——我们还交叉核对了它们的输出字段值，而不仅仅是结构：

• ipc_search、abstract_search、agent_search、patent_free_search、trademark_search 存在参数名称不匹配的问题——工具调用 API 层时使用了 docs_count/docs_start，但这些方法实际接受的是 num_of_rows/page_no，因此名称不匹配的关键字参数被作为查询参数传出，而 KIPRIS 会忽略这些参数，导致请求的结果数未生效。前四个工具的问题已修复并通过实时确认（现在请求 N 条结果会准确返回 N 条）；patent_free_search 的端点经查无论如何都会在服务端忽略行数参数，因此现在会在客户端截取 N 条结果，并对此明确说明。trademark_search 也应用了相同的修复，但——见下文——尚无法通过实时验证。
• KIPRIS 报告的匹配总数（totalCount）会在端点确实提供该数据时显示（ipc/abstract/agent_search，以及验证完成后的 trademark_search）；其他 9 个分页工具（patent_applicant_search、patent_application_number_search、patent_free_search、patent_righter_search 和 5 个外国工具）调用的 KIPRIS 端点根本不会报告总数，因此现在会明确说明这一点，而不会把行数说成总数。
• 我们针对一项真实的已注册专利抽查了字段映射（patent_detail_search 返回的 40 个字段，并与 KIPRIS 原始 XML 交叉参照），也对不同工具的结果进行了交叉核对：patent_applicant_search 的公开日期和公开编号，以及 patent_application_number_search、patent_righter_search 和 patent_free_search 的结果，都通过 patent_detail_search 使用相同申请号重新查询，且完全匹配；5 个外国工具也彼此交叉核对（先通过申请号、再通过国际申请号/公开编号查找一条申请人搜索结果），每次都返回同一条记录。
• patent_righter_search、patent_advanced_search/patent_search 和 5 个外国工具中的 3 个（foreign_patent_applicant_search、foreign_international_application_number_search、foreign_international_open_number_search）此前会在 MCP 协议层因验证错误而崩溃（缺少必填字段、枚举值无效），而不是返回其他工具都会返回的常规 "입력값 검증 오류: ..." 文本——其中两个在 run_tool() 外完全没有 try/except，另外三个则会在自身的 except ValidationError 代码块中重新抛出错误，结果与没有异常处理一样，错误会直接逸出。修复前后，我们都通过实际的 server.call_tool() 路径进行了实时确认。现在全部 17 个工具都有回归测试：测试会在不传入任何参数的情况下调用每个工具，并断言它们都不会抛出异常。

仍未验证的一个工具：

• trademark_search——使用本项目的 KIPRIS API 密钥进行的所有查询，无论搜索词是什么，都会返回结果代码 31（DEADLINE_EXPIRED）。这看起来是因为该密钥可能未获准访问 trademarkInfoSearchService（KIPRIS 会单独审批某些服务，不同于常规专利搜索），而不是此服务存在缺陷——但这也意味着，上述参数名称修复以及该工具的实际输出仍未能使用有效密钥进行确认。

跟踪议题：#9 — trademark_search verification needed。如果你有可访问商标搜索的 KIPRIS API 密钥，并能分享原始 XML 响应（成功或错误均可），请在此议题下留言——我们会用它来验证或修复此工具。

---

路线图

• 升级至 MCP 规范 2026-07-28 — MCP 规范于 2026-07-28 发布，这是一次重大的协议重新设计（无状态会话、server/discover、将 Streamable HTTP 作为唯一未弃用的 HTTP 传输方式、弃用 Roots/Sampling/Logging）。此服务目前固定使用 mcp[cli]>=1.6.0（解析为 1.9.4），早于该版本。待 mcp Python SDK 支持此版本后，我们将升级，并同时将 sse_server.py 从旧版 HTTP+SSE 传输方式（SseServerTransport）迁移到 Streamable HTTP。

---

贡献

完整的开发指南和 CI/CD 设置，请参阅 DEVELOPMENT.md。

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/my-feature
3. 提交更改：git commit -m 'feat: add my feature'
4. 推送：git push origin feature/my-feature
5. 创建 Pull Request

提交前：

ruff check src/   # lint
ruff format src/  # format
pytest test/      # tests (requires KIPRIS_API_KEY)

CI 使用的 KIPRIS_API_KEY 存储为 GitHub Secret — 无需将其提交到仓库。

---

致谢

特别感谢 @haseo-ai 提交了 5 个 Pull Request，大幅扩展了本项目：

• 摘要搜索（AbstractSearchTool）— 按发明摘要搜索专利
• IPC 代码搜索（IpcSearchTool）— 按国际分类代码搜索
• 代理人搜索（AgentSearchTool）— 按注册专利代理人姓名搜索
• 商标搜索（TrademarkSearchTool）— 按韩语关键词搜索商标
• 改进 API 错误处理 — 更稳健地管理 KIPRIS API 响应错误

---

许可证

MIT 许可证