korea-public-data-mcp

An MCP server that enables Claude to directly call South Korea's public data sources (Financial Supervisory Service's OpenDART, Bank of Korea's ECOS, Statistics Korea's KOSIS, and the Public Data Portal) and answer financial, economic, and statistical questions based on actual API responses rather than guesses.

In the same way that MCPs using DART electronic disclosure data answer financial statement questions, this server allows Claude to call its tools to answer questions like "What was this company's revenue last year?", "Show me recent base rate trends", or "What is South Korea's unemployment rate?" based on the latest figures.

The name is temporarily set as korea-public-data-mcp. You can freely change it to any name you like when uploading to GitHub without affecting the code's operation.

Why It Was Built This Way (Design Principles)

The design follows three constraints requested by the person in charge:

1. No LLM/external costs — This server only "fetches" data. It does not call any LLM internally and does not use paid APIs. Since actual reasoning/summarization is done by Claude calling this MCP, server operating costs are virtually zero (excluding electricity/server resources).

2. Prevent API blocking (IP bans) — Government public APIs may temporarily block requests if per-second/daily call limits are exceeded. Therefore:

   • A token bucket rate limiter is placed in front of all API calls to self-throttle the request rate.

   • Repeated identical queries are reused via in-memory cache, and large static files like the DART company list are cached on disk (default 7 days) to prevent re-downloads.

   • Instead of making individual calls for each account item or period, data is fetched in bulk by table or time range (e.g., financial statements retrieve all account items in one call per company; statistics query a start-to-end period in one call).

   • For APIs that support batch operations, like business registration status checks, up to 100 items are bundled into a single call.

   • For 429/5xx responses, exponential backoff is applied with a maximum of 3 retries.

3. Each person runs via Docker — Instead of running a separate server, each team member runs docker build + docker run locally and connects it to their own Claude.

Currently Included APIs (Primary Core Scope)

Implementing all 40+ requested APIs at once would make maintenance difficult, so we first implemented the four core agencies that the person in charge uses most frequently, with high completeness. The rest can be added continuously following the same pattern as the Extension Guide.

API Key Issuance Guide

Even if you haven't obtained keys yet, the server will start normally and the tool list will be visible. However, when you actually call a tool, a message will be returned indicating the key is missing. Apply for the ones you need in order.

Once you have the keys, copy .env.example to .env and fill them in.

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

Quick Start (Docker)

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

Register it in Claude Desktop / Claude Code's MCP settings (claude_desktop_config.json etc.) as shown below.

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

Restart Claude, and the tool list will show dart_*, ecos_*, kosis_*, data_go_kr_* tools. Now you can ask questions like "What was Samsung Electronics' 2023 revenue?" and Claude will call these tools to answer with actual figures.

Local Development/Testing (Without 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로 종료)

Extension Guide (Adding New APIs)

The full list provided by the person in charge (RISS, KIPRIS, National Law Information, National Marketplace, Seoul Open Data Plaza, etc.) can be added by repeating the pattern below. For example, to add a new agency foo:

1. Add a foo entry to API_KEYS in src/korea_public_data_mcp/config.py (env var, issuance URL)

2. Create src/korea_public_data_mcp/clients/foo.py — use core/http_client.get_json to write only the actual endpoint call logic (retry/rate limiting is handled automatically by the shared client)

3. Create src/korea_public_data_mcp/tools/foo_tools.py — wrap the client function with the @mcp.tool() decorator, catch MissingApiKeyError to return an informational message, and use cached_call for caching

4. Add foo_tools.register(mcp) in src/korea_public_data_mcp/server.py

5. Add entries to .env.example and the README table

Thanks to this structure, you don't need to rewrite blocking prevention (rate limiting/caching/batch) logic each time you add a new API.

Next Extension Candidates (Based on the Person in Charge's Request List)

• Law/Administration: National Law Information Open API, Open National Assembly Information API

• Procurement/Business: National Marketplace (g2b), Procurement Data Hub, NTIS National Science & Technology Information

• Academic: RISS, KISTI, National Library of Korea OpenAPI

• Intellectual Property: KIPRIS Plus (patents/trademarks)

• Regional: Seoul Open Data Plaza, Gyeonggi Data Dream

Please let me know the priority or which API to add next, and I will implement it starting from that item.

License

Feel free to use/modify for internal purposes.