fieldcure-mcp-publicdata

FieldCure MCP PublicData.Kr

 

Korean public data API gateway. A Model Context Protocol (MCP) server that lets any MCP client discover, inspect, and call 80,000+ APIs on data.go.kr — weather, real estate, business registration, air quality, transit, and more. Built with C# and the official MCP C# SDK.

Features

• 3 tools — search APIs by keyword, inspect parameters/response fields, call any data.go.kr API
• Automatic serviceKey injection — the API key is added to every request; never leaked to the LLM
• Lazy key resolution — env var → MCP Elicitation → soft-fail chain (no hard-fail on startup). Hosts that support MCP Elicitation can prompt the user for the key on first use; on upstream 401/403 or SERVICE_KEY_IS_NOT_REGISTERED the cached key is invalidated and a re-elicit is attempted (session cap: 2 re-elicits)
• XML → JSON normalization — strips the response/header/body/items wrapper, returns clean JSON
• Error code mapping — translates data.go.kr error codes into Korean guidance messages the LLM can relay directly
• SSRF protection — domain whitelist limits calls to approved government hosts
• EUC-KR support — legacy encoding from older government APIs is auto-detected and converted
• Stateless — no cache, no database, no local files; every call is independent
• Stdio transport — standard MCP subprocess model via JSON-RPC over stdin/stdout

Installation

dotnet tool (recommended)

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

After installation, the fieldcure-mcp-publicdata-kr command is available globally.

From source

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

Prerequisites

1. Sign up at data.go.kr and get your API key

(data.go.kr 회원가입 후 인증키 발급)

1. Subscribe to 목록조회서비스 (Required)

— discover_api and describe_api depend on this API (discover_api, describe_api 도구가 이 API를 사용합니다)

1. Subscribe to each individual API you want to query

(조회하려는 개별 API도 각각 활용신청 필요)

Requirements

• .NET 8.0 Runtime or later

Authentication

This server requires a data.go.kr API key (공공데이터포털 인증키). Key resolution is lazy (on first tool call) and follows the FieldCure MCP Credential ADR:

1. Environment variable — DATA_GO_KR_API_KEY (canonical) or PUBLICDATA_API_KEY (legacy alias)
2. MCP Elicitation — if no env var is found, the server requests the key interactively

on the first tool call (requires a client that supports MCP Elicitation — e.g. Claude Code ≥ 2.1.76, AssistStudio). The resolved key is cached in process memory for the session lifetime and is never written to disk by the server.

1. Soft-fail — if both paths fail, tools/list still works and tool calls return a

structured error message asking the user to set the env var.

--api-key <value> is also accepted as a CLI arg but is intended for manual testing only, not as a supported configuration path.

Setup by host

Claude Code / Claude Desktop — add the key to your MCP config:

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

On Claude Code (≥ 2.1.76), if the env var is omitted the server prompts for the key via Elicitation on first use.

AssistStudio — the key is requested via Elicitation on first use and stored in Windows PasswordVault for subsequent launches; the host then injects it as an env var when starting the server.

Docker / CI — pass the key as a standard environment variable:

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

Key validation and re-elicitation

If the server receives an HTTP 401/403 or a resultCode=22 / SERVICE_KEY_IS_NOT_REGISTERED_ERROR body from data.go.kr, it invalidates the cached key and re-requests via Elicitation (session cap: 2 re-elicits per ApiKeyResolver lifetime). After exhausting retries, the tool returns a soft-fail error message.

Note: On data.go.kr an HTTP 401 can mean either an invalid key or an API that you have not applied for (활용신청). If a re-elicitation prompt appears right after calling an API you haven't subscribed to, entering the same key will produce the final error envelope with details — at that point visit the API's data.go.kr page and apply for access.

Configuration

Claude Desktop

Add to 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 supports MCP Elicitation, so DATA_GO_KR_API_KEY may be omitted — the server will prompt for the key on first tool use.

VS Code (Copilot)

Add to .vscode/mcp.json:

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

From source (without 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

Install the dotnet tool first. AssistStudio does not auto-install external MCP servers (only built-in ones are managed via the AssistStudio auto-update path). The fieldcure-mcp-publicdata-kr command must be on PATH before you add the server, otherwise the connection fails with a generic "server shut down unexpectedly" message. ``bash dotnet tool install -g FieldCure.Mcp.PublicData.Kr # later, to upgrade: dotnet tool update -g FieldCure.Mcp.PublicData.Kr ``

Then: Settings > MCP Servers > Add Server:

| Field | Value | |-------|-------| | Name | PublicData.Kr | | Command | fieldcure-mcp-publicdata-kr | | Arguments | (empty) | | Environment | DATA_GO_KR_API_KEY = your data.go.kr API key (optional — AssistStudio can prompt via Elicitation if unset) | | Description | (auto-filled on first connection) |

Tools

| Tool | Description | |------|-------------| | discover_api | Search data.go.kr APIs by keyword — returns names, providers, endpoint URLs | | describe_api | Get operations, request parameters, and response fields for a specific API | | call_api | Call any data.go.kr API with automatic serviceKey injection and response normalization |

Workflow

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

Search Korean public data APIs on data.go.kr by keyword. Results are deduplicated by service — each API appears once even if it has multiple operations.

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | query | string | Yes | Search keyword (e.g., 미세먼지, 부동산, 사업자) | | page | int | — | Page number (default: 1) | | pageSize | int | — | Results per page (default: 10, max: 50) |

describe_api

Get the request parameters and response fields of a specific API. Use the serviceId from discover_api results.

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | serviceId | string | Yes | Service ID (list_id) from discover_api |

call_api

Call a Korean public data API. The serviceKey is automatically injected — never pass it yourself. If the call fails with ACCESS_DENIED, the user needs to apply for access to that specific API at data.go.kr.

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | url | string | Yes | Full endpoint URL from describe_api results | | params | string | — | Query parameters as a JSON string (not a raw object), e.g. '{"stationName":"종로구","dataTerm":"DAILY"}'. Parameter names must come from describe_api's request_parameters — do not guess. | | maxResults | int | — | Max items to return (default: 20, prevents context overflow) |

Error Code Mapping

When a data.go.kr API returns an error, the server translates it into a Korean guidance message the LLM can relay directly:

| Code | Meaning | LLM receives | |------|---------|--------------| | 12 | NO_OPENAPI_SERVICE | 이 API가 존재하지 않습니다. discover_api로 다시 검색해보세요. | | 20 | ACCESS_DENIED | 이 API에 대한 활용신청이 필요합니다. (포털 링크 포함) | | 22 | KEY_NOT_REGISTERED | API 키가 등록되지 않았습니다. | | 30 | TRAFFIC_EXCEEDED | 일일 호출 한도를 초과했습니다. | | 31 | UNREGISTERED_IP | 이 IP가 등록되지 않았습니다. |

Environment Variables

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | DATA_GO_KR_API_KEY | — | — | data.go.kr API key (인증키). If unset, the server requests it via MCP Elicitation on first tool call. | | PUBLICDATA_API_KEY | — | — | Legacy alias for DATA_GO_KR_API_KEY. Still accepted; prefer the canonical name for new setups. | | PUBLICDATA_TIMEOUT_SECONDS | — | 30 | Per-request timeout | | PUBLICDATA_MAX_RESPONSE_LENGTH | — | 50000 | Maximum response body length in characters |

CLI args (--api-key, --timeout, --max-response-length) override environment variables and are intended for manual testing only — DATA_GO_KR_API_KEY and Elicitation are the supported paths.

Naming note: the API key follows the external service naming convention (DATA_GO_KR_API_KEY), while server-local configuration uses the PUBLICDATA_ prefix. This keeps the key aligned with data.go.kr's own documentation so users don't have to configure it twice, while local tunables stay grouped under a single package namespace.

Security

• API key masking — the serviceKey is replaced with *** in any error output visible to the LLM
• Domain whitelist — call_api only allows requests to approved hosts: api.odcloud.kr, apis.data.go.kr, api.data.go.kr, openapi.data.go.kr, www.law.go.kr, open.neis.go.kr
• Response size limit — configurable via PUBLICDATA_MAX_RESPONSE_LENGTH (default: 50,000 chars)
• No log leaks — the API key is never printed to stdout or stderr

Project Structure

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

Development

# Build
dotnet build

# Test
dotnet test

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

See Also

Part of the AssistStudio ecosystem.

License

MIT