korea-public-data-mcp

This is an MCP server that allows Claude to directly call Korean public data (Financial Supervisory Service OpenDART, Bank of Korea ECOS, Statistics Korea KOSIS, Public Data Portal) and answer financial, economic, and statistical figures based on actual API responses rather than guesswork.

In the same way that MCPs using DART electronic disclosure data answer financial statement questions, Claude will call this server's tools to answer questions like "What was this company's revenue last year?", "Tell me the recent base rate trend", "What is our country's unemployment rate?" based on the latest figures.

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

Why It Was Made This Way (Design Principles)

It was designed to adhere to 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 any paid APIs. Since actual inference/summarization is done by Claude calling this MCP, the server operation cost is virtually zero (excluding electricity/server resources).

2. Prevent API Blocking (IP Ban) — Government public APIs may be temporarily blocked if per-second/daily call limits are exceeded. Therefore:

   • A rate limiter (token bucket) is placed in front of all API calls to slow down automatically.

   • Repeated identical queries reuse memory cache, and large static files like the DART company list prevent re-download via disk cache (default 7 days).

   • Instead of calling individual account items/periods one by one, data is fetched in table units and period ranges at once (e.g., one call per company for all financial statement items, statistics are queried with a start~end period in a single call).

   • APIs that support batching, such as business registration status lookup, send up to 100 items in a single call.

   • For 429/5xx responses, it retries up to 3 times with exponential backoff.

3. Run Each Person's Own Docker — Instead of running a separate server, each team member builds and runs locally with docker build + docker run and connects it to their own Claude.

Related MCP server: OpenDART MCP Server

APIs Currently Included (Primary Core Scope)

Since implementing all 40+ requested APIs at once would make maintenance difficult, we first implemented the core 4 institutions that the person in charge uses most frequently with good completeness. The rest can be added continuously by 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 indicating that the key is missing will be returned, so apply for the ones you need in order.

Once you receive the keys, copy .env.example to .env and fill it 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 the MCP settings of Claude Desktop / Claude Code (such as claude_desktop_config.json) as shown below.

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

When you restart Claude, the dart_*, ecos_*, kosis_*, data_go_kr_* tools will appear in the tool list. Now, when you ask a question like "삼성전자 2023년 매출액 알려줘", Claude will call these tools and answer based on 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 a New API)

The entire list provided by the person in charge (RISS, KIPRIS, 국가법령정보, 나라장터, 서울 열린데이터광장, 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 — write only the actual endpoint call logic using core/http_client.get_json (retry/rate limiting is handled automatically by the common client)

3. Create src/korea_public_data_mcp/tools/foo_tools.py — wrap the client function with the @mcp.tool() decorator, catch MissingApiKeyError and return a guidance message, cache with cached_call

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

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

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

Next Extension Candidates (Based on Requested List)

• Law/Administration: 국가법령정보 Open API, 열린국회정보 API

• Procurement/Projects: 나라장터(g2b), 조달데이터허브, NTIS 국가과학기술정보

• Academic: RISS, KISTI, 국립중앙도서관 OpenAPI

• Intellectual Property: KIPRIS Plus (patents/trademarks)

• Regional: 서울 열린데이터광장, 경기데이터드림

If you let me know the priority or which API to add next, I will implement from that item onward.

License

Feel free to use/modify for internal purposes.