publicdata-kr

FieldCure MCP PublicData.Kr

韓国の公共データ API ゲートウェイです。Model Context Protocol (MCP) サーバーとして、あらゆる MCP クライアントから data.go.kr の 80,000 件以上の API（天気、不動産、事業者登録、大気質、交通機関など）を検索、確認、呼び出せます。C# と公式の MCP C# SDK で構築されています。

機能

• 3 つのツール — キーワードで API を検索し、パラメーターやレスポンスフィールドを確認して、任意の data.go.kr API を呼び出します
• serviceKey の自動付与 — API キーはすべてのリクエストに追加され、LLM に漏れることはありません
• キーの遅延解決 — 環境変数 → MCP Elicitation → ソフトフェイルの順で処理します（起動時にハードフェイルしません）。MCP Elicitation に対応するホストでは、初回使用時にキーの入力をユーザーに求められます。上流から 401/403 または SERVICE_KEY_IS_NOT_REGISTERED が返された場合、キャッシュされたキーを無効化して再度 Elicitation を試みます（セッションごとの再 Elicitation は最大 2 回）
• XML → JSON の正規化 — response/header/body/items のラッパーを取り除き、整形された JSON を返します
• エラーコードのマッピング — data.go.kr のエラーコードを、LLM がそのままユーザーに伝えられる韓国語のガイダンスメッセージに変換します
• SSRF 対策 — ドメインの許可リストにより、承認済みの政府ホストへの呼び出しに限定します
• EUC-KR 対応 — 古い政府 API で使用されているレガシーエンコーディングを自動検出して変換します
• ステートレス — キャッシュ、データベース、ローカルファイルはありません。各呼び出しは独立しています
• Stdio トランスポート — 標準的な MCP サブプロセスモデルを使用し、標準入力／標準出力経由で JSON-RPC を行います

インストール

dotnet tool（推奨）

dotnet tool install -g FieldCure.Mcp.PublicData.Kr

インストール後、fieldcure-mcp-publicdata-kr コマンドをグローバルに使用できます。

ソースから

git clone https://github.com/fieldcure/fieldcure-mcp-publicdata.git
cd fieldcure-mcp-publicdata
dotnet build

前提条件

1. data.go.kr に登録し、API キーを取得します （data.go.kr 회원가입 후 인증키 발급）
2. 목록조회서비스 に申し込みます（必須） — discover_api と describe_api はこの API に依存します （discover_api, describe_api 도구가 이 API를 사용합니다）
3. 利用する個々の API に申し込みます （조회하려는 개별 API도 각각 활용신청 필요）

要件

• .NET 8.0 Runtime 以降

認証

このサーバーには data.go.kr API キー（공공데이터포털 인증키）が必要です。キーは 遅延（最初のツール呼び出し時）に解決され、FieldCure MCP Credential ADR に従って次の順に処理されます。

1. 環境変数 — DATA_GO_KR_API_KEY（正式名）または PUBLICDATA_API_KEY（旧エイリアス）
2. MCP Elicitation — 環境変数が見つからない場合、サーバーは最初のツール呼び出し時に 対話形式でキーを要求します（MCP Elicitation に対応するクライアントが必要です。例：Claude Code ≥ 2.1.76、AssistStudio）。解決されたキーはセッション中、プロセスメモリにキャッシュされ、 サーバーによってディスクに書き込まれることはありません。
3. ソフトフェイル — どちらの方法でも失敗した場合も、tools/list は引き続き動作し、ツール呼び出しは 環境変数を設定するようユーザーに求める構造化エラーメッセージを返します。

--api-key <value> も CLI 引数として指定できますが、手動テスト専用であり、 サポート対象の設定方法ではありません。

ホスト別のセットアップ

Claude Code / Claude Desktop — キーを MCP 設定に追加します。

{
  "mcpServers": {
    "publicdata-kr": {
      "command": "fieldcure-mcp-publicdata-kr",
      "env": {
        "DATA_GO_KR_API_KEY": "<your-key>"
      }
    }
  }
}

Claude Code（≥ 2.1.76）では、環境変数を省略すると、初回使用時に Elicitation を通じてキーの入力が求められます。

AssistStudio — 初回使用時に Elicitation を通じてキーの入力が求められ、次回以降の起動に備えて Windows PasswordVault に保存されます。その後、ホストがサーバーの起動時にキーを環境変数として渡します。

Docker / CI — 標準の環境変数としてキーを渡します。

docker run -e DATA_GO_KR_API_KEY=<your-key> ...

キーの検証と再入力

data.go.kr から HTTP 401/403、または resultCode=22 / SERVICE_KEY_IS_NOT_REGISTERED_ERROR の本文を受信すると、キャッシュされたキーを無効化し、Elicitation を通じて再入力を求めます（ApiKeyResolver の存続期間中、再入力は最大 2 回）。再試行を使い切ると、ツールはソフトフェイルのエラーメッセージを返します。

注： data.go.kr では、HTTP 401 は無効なキーを意味する場合と、申請していない（활용신청）API を意味する場合があります。申し込んでいない API を呼び出した直後に再入力のプロンプトが表示された場合、同じキーを入力すると詳細を含む最終エラーのエンベロープが返されます。その場合は、API の data.go.kr ページにアクセスして利用を申請してください。

設定

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "publicdata-kr": {
      "command": "fieldcure-mcp-publicdata-kr",
      "env": {
        "DATA_GO_KR_API_KEY": "YOUR_DATA_GO_KR_API_KEY"
      }
    }
  }
}

Claude Code（v2.1.76+）

claude mcp add publicdata-kr -- fieldcure-mcp-publicdata-kr

Claude Code は MCP Elicitation をサポートしているため、DATA_GO_KR_API_KEY は省略できます。初めてツールを使用するときに、サーバーがキーの入力を求めます。

VS Code（Copilot）

.vscode/mcp.json に追加します。

{
  "servers": {
    "publicdata-kr": {
      "command": "fieldcure-mcp-publicdata-kr",
      "env": {
        "DATA_GO_KR_API_KEY": "YOUR_DATA_GO_KR_API_KEY"
      }
    }
  }
}

ソースから（dotnet tool を使用しない場合）

{
  "mcpServers": {
    "publicdata-kr": {
      "command": "dotnet",
      "args": [
        "run",
        "--project", "C:\\path\\to\\fieldcure-mcp-publicdata\\src\\FieldCure.Mcp.PublicData.Kr"
      ],
      "env": {
        "DATA_GO_KR_API_KEY": "YOUR_DATA_GO_KR_API_KEY"
      }
    }
  }
}

AssistStudio

まず dotnet tool をインストールしてください。 AssistStudio は外部 MCP サーバーを自動インストールしません（AssistStudio の自動更新機能で管理されるのは組み込みのものだけです）。 サーバーを追加する前に、fieldcure-mcp-publicdata-kr コマンドが PATH 上にある必要があります。そうでない場合、接続は「server shut down unexpectedly」という一般的なメッセージで失敗します。

dotnet tool install -g FieldCure.Mcp.PublicData.Kr
# later, to upgrade:
dotnet tool update -g FieldCure.Mcp.PublicData.Kr

次に、Settings > MCP Servers > Add Server を選択します。

フィールド	値
名前	PublicData.Kr
コマンド	fieldcure-mcp-publicdata-kr
引数	(空欄)
環境変数	DATA_GO_KR_API_KEY = お使いの data.go.kr API キー (任意 — 未設定の場合、AssistStudio は Elicitation を通じて入力を求めることができます)
説明	(初回接続時に自動入力)

ツール

ツール	説明
discover_api	キーワードで data.go.kr API を検索します — 名前、提供元、エンドポイント URL を返します
describe_api	特定の API の操作、リクエストパラメーター、レスポンスフィールドを取得します
call_api	serviceKey の自動挿入とレスポンスの正規化を行い、任意の data.go.kr API を呼び出します

ワークフロー

1. discover_api("미세먼지")
   → { serviceId: "15073861", serviceName: "한국환경공단_에어코리아_대기오염정보", ... }

2. describe_api("15073861")
   → { operations: [{ name: "getMsrstnAcctoRltmMesureDnsty", url: "...", requestParameters: [...] }] }

3. call_api(url: "http://apis.data.go.kr/B552584/ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty",
            params: '{"stationName": "종로구", "dataTerm": "DAILY", "returnType": "json"}')
   → { totalCount: 24, items: [{ stationName: "종로구", pm10Value: "45", ... }] }

discover_api

キーワードで data.go.kr の韓国公共データ API を検索します。結果はサービス単位で重複が除かれます。複数の操作がある API も、それぞれ 1 回だけ表示されます。

パラメーター	型	必須	説明
query	string	はい	検索キーワード（例：미세먼지、부동산、사업자）
page	int	—	ページ番号（デフォルト：1）
pageSize	int	—	1 ページあたりの結果数（デフォルト：10、最大：50）

describe_api

特定の API のリクエストパラメーターとレスポンスフィールドを取得します。discover_api の結果に含まれる serviceId を使用してください。

パラメーター	型	必須	説明
serviceId	string	はい	discover_api の list_id（サービス ID）

call_api

韓国の公共データ API を呼び出します。serviceKey は自動的に挿入されるため、自分で渡さないでください。呼び出しが ACCESS_DENIED で失敗した場合は、ユーザーが data.go.kr で該当する API の利用申請を行う必要があります。

パラメーター	型	必須	説明
url	string	はい	describe_api の結果に含まれる完全なエンドポイント URL
params	string	—	JSON 文字列（生のオブジェクトではありません）としてのクエリパラメーター。例：'{"stationName":"종로구","dataTerm":"DAILY"}'。パラメーター名は describe_api の request_parameters にあるものを使用してください。推測しないでください。
maxResults	int	—	返す最大項目数（デフォルト：20。コンテキストのあふれを防ぎます）

エラーコードの対応

data.go.kr API がエラーを返した場合、サーバーは LLM がそのままユーザーに伝えられる韓国語の案内メッセージに変換します。

コード	意味	LLM が受け取る内容
12	NO_OPENAPI_SERVICE	이 API가 존재하지 않습니다. discover_api로 다시 검색해보세요.
20	ACCESS_DENIED	이 API에 대한 활용신청이 필요합니다. (포털 링크 포함)
22	KEY_NOT_REGISTERED	API 키가 등록되지 않았습니다.
30	TRAFFIC_EXCEEDED	일일 호출 한도를 초과했습니다.
31	UNREGISTERED_IP	이 IP가 등록되지 않았습니다.

環境変数

変数	必須	デフォルト	説明
DATA_GO_KR_API_KEY	—	—	data.go.kr API キー（認証キー）。設定されていない場合、サーバーは初回のツール呼び出し時に MCP Elicitation を通じてキーを要求します。
PUBLICDATA_API_KEY	—	—	DATA_GO_KR_API_KEY の従来の別名。現在も使用できますが、新しい設定では正式名称を推奨します。
PUBLICDATA_TIMEOUT_SECONDS	—	30	リクエストごとのタイムアウト
PUBLICDATA_MAX_RESPONSE_LENGTH	—	50000	最大レスポンス本文長（文字数）

CLI 引数（--api-key、--timeout、--max-response-length）は環境変数より優先されます。 手動テスト専用であり、サポートされる設定方法は DATA_GO_KR_API_KEY と Elicitation です。

命名に関する注記： API キーは外部サービスの命名規則（DATA_GO_KR_API_KEY）に従い、 サーバー固有の設定には PUBLICDATA_ プレフィックスを使用します。 これにより、キーの名称を data.go.kr のドキュメントに合わせて、ユーザーが二重に設定する必要がないようにしつつ、 ローカルの調整可能な設定は単一のパッケージ名前空間にまとめています。

セキュリティ

• API キーのマスキング — LLM に表示されるエラー出力では、serviceKey は *** に置き換えられます
• ドメインの許可リスト — call_api は、承認済みホスト（api.odcloud.kr、apis.data.go.kr、api.data.go.kr、openapi.data.go.kr、www.law.go.kr、open.neis.go.kr）へのリクエストのみを許可します
• レスポンスサイズの制限 — PUBLICDATA_MAX_RESPONSE_LENGTH で設定できます（デフォルト：50,000 文字）
• ログへの漏えいなし — API キーが stdout または stderr に出力されることはありません

プロジェクト構成

src/FieldCure.Mcp.PublicData.Kr/
├── Program.cs                       # MCP server entry point (stdio); no startup hard-fail
├── Services/
│   ├── ApiKeyResolver.cs            # env var → MCP Elicitation → soft-fail chain + cache + retry cap
│   ├── InvalidApiKeyException.cs    # Signals upstream auth rejection (HTTP 401/403 or body error)
│   ├── KeyedCall.cs                 # Tool-side resolve → run → invalidate → retry helper
│   ├── PublicDataHttpClient.cs      # HTTP proxy with serviceKey injection + auth-error detection
│   ├── DomainWhitelist.cs           # SSRF prevention via host whitelist
│   ├── ResponseNormalizer.cs        # XML→JSON conversion, wrapper removal
│   └── ErrorCodeMapper.cs           # Error code → Korean guidance messages
└── Tools/
    ├── DiscoverApiTool.cs           # discover_api
    ├── DescribeApiTool.cs           # describe_api
    └── CallApiTool.cs               # call_api

開発

# Build
dotnet build

# Test
dotnet test

# Pack as dotnet tool
dotnet pack src/FieldCure.Mcp.PublicData.Kr -c Release

関連項目

AssistStudio ecosystem の一部です。

ライセンス

MIT