Skip to main content
Glama
korea-public-data-mcp

korea-public-data-mcp

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: korean-stat-mcp

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.

Agency

Provided Tools

Notes

금융감독원 OpenDART

dart_search_company, dart_get_financial_statements, dart_get_company_disclosures

Use in order: company name search → corp_code → financial statements/disclosures

한국은행 ECOS

ecos_get_key_indicator, ecos_search_statistics, ecos_get_statistic_data

Base rate/exchange rate/GDP/CPI can be queried directly by name

통계청 KOSIS

kosis_search_statistics, kosis_get_statistics_data

After keyword search, batch query by period range in table units

공공데이터포털 (data.go.kr)

data_go_kr_check_business_status, data_go_kr_generic_get

Business registration status supports batch (up to 100 items), other services are temporarily handled via a generic GET tool

한국수출입은행

koreaexim_get_exchange_rates, koreaexim_get_loan_rates, koreaexim_get_international_rates

Issued from koreaexim.go.kr's own site, not data.go.kr. Exchange rates/loan rates/international rates are separate API products, so you must apply for each service and receive 3 authkeys. Data may be empty when queried before 11:00 on business days or on non-business days.

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.

Agency

Issuance Location

Notes

OpenDART

https://opendart.fss.or.kr → Register → [Apply/Manage Auth Key]

Issued immediately upon registration, fastest

ECOS

https://ecos.bok.or.kr/api/#/

Open API auth key application, within immediate~1 day

KOSIS

https://kosis.kr/openapi/index/index.jsp

"OpenAPI Application for Use", approval may take time

공공데이터포털

https://www.data.go.kr → desired service detail page → [Apply for Use]

Separate application needed per service. Recommend applying for "National Tax Service_Business Registration Information Verification and Status Inquiry" first

한국수출입은행

https://www.koreaexim.go.kr/ir/HPHKIR019M01 → Open API specification → Apply for auth key issuance

Not via data.go.kr but issued directly from koreaexim.go.kr. immediate~same day

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.

Available Tools

13 tools
dart_get_company_disclosuresC

기간 내 회사 공시 목록을 조회한다. 날짜는 YYYYMMDD 형식 (예: 20240101).

Inputs: end_date (required), corp_code (required), start_date (required).

dart_get_financial_statementsB

OpenDART 단일회사 전체 재무제표를 조회한다. corp_code는 dart_search_company로 먼저 찾을 것. report: '사업보고서'(연간, 기본값) | '1분기' | '반기' | '3분기'. fs_div: 'CFS'(연결재무제표, 기본값) | 'OFS'(별도재무제표).

Inputs: year (required), corp_code (required), fs_div, report.

dart_search_companyA

회사명으로 OpenDART corp_code를 검색한다. 재무제표/공시 조회 전에 먼저 호출해서 정확한 corp_code를 확인하는 용도. 예: company_name='삼성전자'.

Inputs: company_name (required), limit.

data_go_kr_check_business_statusA

사업자등록번호(하이픈 없이 10자리) 상태를 최대 100건까지 한 번에 배치 조회한다. 예: business_numbers=['1234567890', '0987654321'].

Inputs: business_numbers (required).

data_go_kr_generic_getA

공공데이터포털의 다른 서비스(사전에 클라이언트 코드가 없는 것)를 호출할 때 쓰는 범용 도구. base_url/path는 해당 서비스의 활용신청 상세페이지에 나온 End Point를 그대로 넣고, params에는 serviceKey를 제외한 나머지 파라미터만 넣는다(serviceKey는 자동으로 채워짐). 자주 쓰는 서비스는 전용 client/tool을 새로 만드는 것을 권장 (README 확장 가이드 참고).

Inputs: path (required), params (required), base_url (required).

ecos_get_key_indicatorA

자주 찾는 거시경제 지표를 이름으로 바로 조회한다. indicator: '기준금리' | '원달러환율' | 'GDP성장률' | '소비자물가지수'. start/end 형식은 지표의 주기에 맞춰야 함(월간=YYYYMM, 분기=YYYYQn, 일간=YYYYMMDD).

Inputs: end (required), start (required), indicator (required).

ecos_get_statistic_dataB

ecos_search_statistics로 찾은 stat_code로 실제 수치 데이터를 조회한다. cycle: D(일)/M(월)/Q(분기)/A(연).

Inputs: end (required), cycle (required), start (required), stat_code (required), +2 more.

ecos_search_statisticsA

키워드로 ECOS 통계표(stat_code)를 검색한다. 사전 등록되지 않은 지표를 찾을 때 사용.

Inputs: keyword (required).

koreaexim_get_exchange_ratesA

한국수출입은행 현재환율(매매기준율/전신환매매율)을 조회한다. search_date: YYYYMMDD 또는 YYYY-MM-DD, 생략 시 당일 영업일 기준. 영업일 11시 이전이나 비영업일 조회 시 데이터가 비어 있을 수 있다.

Inputs: search_date.

koreaexim_get_international_ratesA

한국수출입은행 국제금리(LIBOR 등)를 조회한다. search_date: YYYYMMDD 또는 YYYY-MM-DD, 생략 시 당일 영업일 기준.

Inputs: search_date.

koreaexim_get_loan_ratesA

한국수출입은행 대출금리(고정기준금리)를 조회한다. search_date: YYYYMMDD 또는 YYYY-MM-DD, 생략 시 당일 영업일 기준.

Inputs: search_date.

kosis_get_statistics_dataB

kosis_search_statistics로 찾은 org_id/tbl_id의 통계자료를 표 단위로 일괄 조회한다. prd_se: 'Y'(연)|'Q'(분기)|'M'(월). start_prd~end_prd로 기간 범위를 지정하면 여러 연도/월을 한 번의 호출로 받아올 수 있다 (개별 호출 반복 금지).

Inputs: org_id (required), tbl_id (required), prd_se, end_prd, +2 more.

kosis_search_statisticsC

키워드로 KOSIS 통계표(org_id/tbl_id)를 검색한다. 예: '실업률', '인구', '출생아수'.

Inputs: keyword (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool is clearly scoped to a specific data source and operation (e.g., search, get data, check status). Tools within the same source have distinct purposes (e.g., dart_search_company vs. dart_get_financial_statements), and the ECOS/KOSIS pairs are well-separated by search vs. retrieval. No overlapping or ambiguous tools.

    Naming Consistency5/5

    All tool names follow a consistent `source_verb_noun` pattern in snake_case (e.g., dart_search_company, ecos_get_key_indicator, koreaexim_get_exchange_rates). The naming convention is uniform across all 13 tools, making it predictable for an agent.

    Tool Count5/5

    13 tools is a well-balanced count for a server aggregating multiple Korean public data sources. Each source (OpenDART, ECOS, KOSIS, data.go.kr, Korea Eximbank) gets a focused set of 2-4 tools, covering search and data retrieval without becoming bloated.

    Completeness4/5

    The tool set covers core operations for each integrated source: search, retrieve financial/statistical data, check business status, and fetch exchange/loan rates. The inclusion of a generic `data_go_kr_generic_get` tool fills gaps for unlisted data.go.kr services. Minor absences like more granular OpenDART disclosure filters or additional KOSIS metadata tools do not critically hinder coverage.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables natural language querying of Korean statistical data from KOSIS, including population, employment, GDP, housing prices, and more, with support for regional and trend analysis.
      8
      10 npm
      18
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying Korean official statistics from KOSIS via natural language in MCP clients like Claude Desktop, wrapping the KOSIS OpenAPI for search, data retrieval, and metadata exploration.
      MIT