korea-public-data-mcp

韓国の公共データ（金融監督院 OpenDART、韓国銀行 ECOS、統計庁 KOSIS、公共データポータル）を Claudeが直接呼び出し、財務・経済・統計数値を推測ではなく実際のAPI応答に基づいて回答させる MCPサーバーです。

DART電子公示データを活用して財務諸表の質問に答えるMCPと同様の方法で、 「この会社の昨年の売上は？」「最近の基準金利の推移を教えて」「韓国の失業率は何％？」といった 質問に対し、Claudeがこのサーバーのツールを呼び出し、最新の数値に基づいて回答します。

名前は仮でkorea-public-data-mcpとしています。GitHubにアップロードする際に任意の名前に 変更しても、コードの動作には影響しません。

なぜこのように作ったか（設計原則）

担当者様からご依頼いただいた3つの制約を守る方向で設計しました。

1. LLM/外部コストなし — このサーバーはデータを「取得するだけ」です。内部でLLMを 呼び出さず、有料APIも使用しません。実際の推論/要約はこのMCPを呼び出すClaudeが 行うため、サーバー運用コストは実質0円（電気代/サーバーリソースを除く）です。

2. APIブロック（IP Ban）防止 — 政府公共APIは秒間/日間の呼び出し制限を超えると一時的に ブロックされる場合があります。そのため：

   • すべてのAPI呼び出しの前に秒間呼び出し数制限（トークンバケット） を設け、自ら速度を落とします。

   • 同じ質問を繰り返す場合はメモリキャッシュで再利用し、DART企業リストのような大きな静的ファイルは ディスクキャッシュ（デフォルト7日間）で再ダウンロードを防ぎます。

   • 勘定科目/期間を個別に呼び出さず、表単位・期間範囲単位で一度に取得します （例：財務諸表は企業ごとに1回の呼び出しで全勘定科目を取得、統計は開始～終了期間を一度に照会）。

   • 事業者登録状態照会のようにバッチがサポートされているAPIは最大100件を1回の呼び出しにまとめて送信します。

   • 429/5xx応答には指数バックオフで最大3回まで再試行します。

3. 各自Dockerで実行 — 別途サーバーを立てず、チームメンバー各自がローカルで docker build + docker runで起動し、自分のClaudeに接続する構造です。

Related MCP server: OpenDART MCP Server

現在含まれているAPI（1次コア範囲）

全リクエストリスト（40件以上）を一度に実装するとメンテナンスが困難になるため、担当者様が 最も頻繁に利用するコア4機関から先に完成度高く実装しました。残りは拡張ガイドに従い、同じパターンで順次追加可能です。

APIキー発行ガイド

まだキーを取得していなくてもサーバーは正常に起動し、ツール一覧も表示されます。ただし、実際にツールを 呼び出すとキーがない旨の案内メッセージが返されるため、必要なものから順に申請してください。

キーを取得したら、.env.exampleを.envにコピーして記入してください。

cp .env.example .env
# .env 파일을 열어 발급받은 키 입력

クイックスタート（Docker）

git clone <이 레포 주소>
cd korea-public-data-mcp
cp .env.example .env   # 키 채워넣기 (없어도 일단 진행 가능)
docker build -t korea-public-data-mcp .

Claude Desktop / Claude CodeのMCP設定（claude_desktop_config.jsonなど）に以下のように登録します。

{
  "mcpServers": {
    "korea-public-data": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/절대경로/korea-public-data-mcp/.env",
        "korea-public-data-mcp"
      ]
    }
  }
}

Claudeを再起動すると、ツール一覧にdart_*、ecos_*、kosis_*、data_go_kr_*ツールが 表示されます。「サムスン電子の2023年の売上高を教えて」といった質問をすると、Claudeがこれらのツールを 呼び出して実際の数値で回答します。

ローカル（Dockerなし）での開発/テスト

python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest
pytest -q                      # 키 없이도 통과하는 스모크 테스트
python -m korea_public_data_mcp.server   # stdio로 직접 실행해보기 (Ctrl+C로 종료)

拡張ガイド（新しいAPIの追加）

担当者様からいただいた全リスト（RISS、KIPRIS、国家法令情報、나라장터、ソウル開放データ広場など）は、 以下のパターンをそのまま繰り返せば追加できます。例として新しい機関fooを追加する場合：

1. src/korea_public_data_mcp/config.pyのAPI_KEYSにfoo項目を追加（env var、発行URL）

2. src/korea_public_data_mcp/clients/foo.pyを作成 — core/http_client.get_jsonを使用して 実際のエンドポイント呼び出しロジックのみ記述（再試行/速度制限は共通クライアントが自動処理）

3. src/korea_public_data_mcp/tools/foo_tools.pyを作成 — @mcp.tool()デコレータで client関数をラップし、MissingApiKeyErrorをキャッチして案内メッセージを返し、cached_callでキャッシュ

4. src/korea_public_data_mcp/server.pyでfoo_tools.register(mcp)の1行を追加

5. .env.example、README表に項目を追加

この構造により、新しいAPIを追加してもブロック防止（速度制限/キャッシュ/バッチ）ロジックを毎回新たに記述する必要がありません。

次の拡張候補（担当者リクエストリスト基準）

• 法律/行政：国家法令情報Open API、열린국회정보 API

• 調達/事業：나라장터(g2b)、調達データハブ、NTIS国家科学技術情報

• 学術：RISS、KISTI、国立中央図書館OpenAPI

• 知的財産権：KIPRIS Plus（特許・商標）

• 地域：ソウル開放データ広場、경기데이터드림

優先順位や次に追加するAPIをお知らせいただければ、その項目から順次実装いたします。

ライセンス

内部用として自由に使用/修正してください。