korea-public-data-mcp

韓国の公共データ（금융감독원 OpenDART、한국은행 ECOS、통계청 KOSIS、공공데이터포털）を Claude が直接呼び出して、財務・経済・統計の数値を推測ではなく実際の API 応答に基づいて回答させる MCP サーバーです。

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

名前は仮に korea-public-data-mcp としています。GitHub に公開するときにお好きな名前に 変えても、コードの動作には影響しません。

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

担当者様がリクエストされた三つの制約を守る方向で設計しました。

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

2. API 遮断（IP バン）防止 — 政府の公共 API は、秒間/1日の呼び出し制限を超えると一時的に 遮断される場合があります。そこで：

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

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

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

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

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

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

現在含まれる API（一次の主要範囲）

全体のリクエスト一覧（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 をお知らせいただければ、その項目から続けて実装します。

ライセンス

社内用に自由に使用・修正してください。