MCP KIPRIS

MCP KIPRIS

English | 한국어 →

Claude のような AI アシスタントが、韓国知的財産庁（KIPO）が運営する韓国の公式特許・商標データベース KIPRIS に直接アクセスできる MCP（Model Context Protocol） サーバーです。

---

KIPRIS を利用する理由

韓国は、世界の特許出願件数上位 5 か国の一つです。Samsung、LG、SK Hynix、Hyundai、POSCO などの企業は毎年数万件の特許を出願しており、すべて KIPRIS で検索できます。

この MCP サーバーを使えば、ユーザーが韓国語の KIPRIS ウェブポータルを操作しなくても、Claude（または MCP 対応の AI クライアント）が自然言語で特許を検索できます。

一般的なユースケース：

• 特許出願前の先行技術調査
• 韓国のテクノロジー企業に関する競合情報の収集
• 特定の技術分野における 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. 非商用利用の場合、キーは無料で、1 日あたりのリクエスト上限が設定されています。

---

レート制限

KIPRIS への送信リクエストは、プロセス内レートリミッターによって制限されており、1 分あたり 60 件が上限です（RateLimiter のデフォルト値。src/mcp_kipris/kipris/rate_limiter.py）。上限に達すると、リクエストは失敗せずに待機して自動的に再試行されるため、ユーザー側での操作は不要です。この制限は現在、環境変数では設定できません。

これは このサーバー が KIPRIS にリクエストを送信する速度だけを制限するもので、KIPRIS 開発者ポータルにおける API キーごとの 1 日あたりのリクエスト上限とは別のものです。

---

機能

韓国特許の検索

ツール	説明
patent_applicant_search	出願人名で特許を検索
patent_free_search	フリーテキストのキーワードで検索
patent_application_number_search	出願番号で検索
patent_righter_search	権利者名で検索
patent_detail_search	出願番号から特許の詳細を取得します。約 65 種類の利用可能なフィールド（書誌情報、IPC、要約、請求項、出願人／発明者／代理人、優先権、法的状態、研究開発資金など）から任意の組み合わせを選択する fields パラメーターに対応しています。省略すると、短いデフォルトの概要を返します
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 マーケットプレイスから直接インストールできます。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/ には 2 種類のテストがあります。

• test/unit/ — 完全にモック化されており、ネットワークアクセスは不要です。KIPRIS_API_KEY も必要ありません。pytest.mark.unit でマークされています。
• ルート階層の test_*.py — 実際の KIPRIS API を呼び出すため、有効な KIPRIS_API_KEY が必要です。pytest で検出可能なケースは 1 つで、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

Lint とフォーマット

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 でパイプライン全体が実行されます。

ステップ	ツール	備考
Lint	ruff check	PEP 8 とスタイルルール
フォーマット	ruff format --check	一貫したフォーマットを適用します
テスト	pytest	主にモック化された単体テストと、実 API を使った統合テスト 1 件です。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 →

---

既知の制限事項

17 個すべてのツールを、稼働中の KIPRIS API に対して実行しました。そのうち 16 個は、「適切な形式の出力を返す」ことにとどまらず、出力のフィールド値も照合して検証しました。形式だけでなく、値も確認しています。

• ipc_search、abstract_search、agent_search、patent_free_search、trademark_search では、パラメーター名が一致していませんでした。ツールは API 層を docs_count／docs_start で呼び出していましたが、これらのメソッドが実際に受け取るのは num_of_rows／page_no だったため、一致しないキーワード引数がクエリパラメーターとして渡されても KIPRIS に無視され、要求した件数が反映されていませんでした。最初の 4 つは修正し、稼働中の API で確認済みです（現在は N 件を要求すると、ちょうど N 件が返ります）。一方、patent_free_search のエンドポイントは、サーバー側で行数パラメーターを無視することが判明したため、クライアント側で N 件に切り詰め、その旨を示すようにしました。trademark_search にも同じ修正を適用しましたが、下記のとおり、稼働中の API では確認できていません。
• 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 プロトコルレベルでクラッシュしていました。2 個は run_tool() の前後に try／except がまったくなく、残りの 3 個は独自の except ValidationError ブロック内で再送出していたため、ブロックがない場合と同様にエラーがそのまま伝播していました。修正の前後で、実際の server.call_tool() 経由で動作を確認しました。現在は、引数なしで各ツールを呼び出し、どのツールも例外を発生させないことを検証する回帰テストで、17 個すべてのツールを対象としています。

未検証のツールは 1 つです。

• trademark_search — このプロジェクトの KIPRIS API キーでは、検索語にかかわらず、どのクエリに対しても結果コード 31（DEADLINE_EXPIRED）が返されます。これは、このキーが trademarkInfoSearchService の利用を許可されていないことが原因と思われます（KIPRIS では通常の特許検索とは別に、一部のサービスが承認されます）。このサーバーの不具合ではないと考えられますが、上記のパラメーター名の修正と、ツールの実際の出力は、まだ利用可能なキーで確認できていません。

追跡用 Issue：#9 — trademark_search verification needed。商標検索にアクセスできる KIPRIS API キーをお持ちで、未加工 XML のレスポンス（成功・エラーを問いません）を共有できる場合は、こちらにコメントしてください。このツールの検証と修正に使用します。

---

ロードマップ

• MCP 仕様 2026-07-28 へのアップグレード — 2026-07-28 にリリースされた MCP specification は、プロトコルの大幅な再設計です（ステートレスセッション、server/discover、非推奨ではない唯一の HTTP トランスポートとしての Streamable 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. リポジトリをフォークします
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 として保存されているため、コミットする必要はありません。

---

謝辞

このプロジェクトを大きく拡張する 5 件のプルリクエストを送ってくださった @haseo-ai に、心より感謝いたします。

• 抄録検索（AbstractSearchTool）— 発明の抄録から特許を検索
• IPC コード検索（IpcSearchTool）— 国際分類コードで検索
• 代理人検索（AgentSearchTool）— 登録済みの特許代理人名から検索
• 商標検索（TrademarkSearchTool）— 韓国語の商標キーワード検索
• API エラーハンドリングの改善 — KIPRIS API レスポンスに対する、より堅牢なエラー管理

---

ライセンス

MIT License