korea-public-data-mcp
This MCP server lets Claude directly query a wide range of Korean public data APIs and answer questions using live data, with natural Korean-language requests instead of remembering tool names.
Search government support programs and public procurement notices across 9 sources, including business support programs, K-Startup, and all procurement stages (발주계획, 조달요청, 사전규격, 입찰공고, 낙찰, 계약) via
gov_searchandgov_list_sources.Retrieve corporate financial statements, disclosures, and company codes from OpenDART (e.g., Samsung Electronics annual reports).
Pull macroeconomic indicators and statistics from ECOS (base rate, USD/KRW exchange rate, GDP growth, CPI), KOSIS national statistics, and Korea Exim Bank exchange/loan/international rates.
Search patents and utility models via KIPRIS, school information via NEIS, national R&D projects via NTIS, Seoul Institute research reports, and KCI academic articles (some keys pending).
Look up company employee counts and hiring/leaving trends via National Pension Service data, plus search Wanted job postings and HRD-Net KDT training courses (keys pending).
Use
data_go_kr_generic_getto call any other public-data-portal service without code changes, and batch-check business registration numbers withdata_go_kr_check_business_status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@korea-public-data-mcp 삼성전자 2023년 매출액 알려줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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).
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.
Run Each Person's Own Docker — Instead of running a separate server, each team member builds and runs locally with
docker build+docker runand 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 |
| Use in order: company name search → corp_code → financial statements/disclosures |
한국은행 ECOS |
| Base rate/exchange rate/GDP/CPI can be queried directly by name |
통계청 KOSIS |
| After keyword search, batch query by period range in table units |
공공데이터포털 (data.go.kr) |
| Business registration status supports batch (up to 100 items), other services are temporarily handled via a generic GET tool |
한국수출입은행 |
| 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 | Open API auth key application, within immediate~1 day | |
KOSIS | "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:
Add a
fooentry toAPI_KEYSinsrc/korea_public_data_mcp/config.py(env var, issuance URL)Create
src/korea_public_data_mcp/clients/foo.py— write only the actual endpoint call logic usingcore/http_client.get_json(retry/rate limiting is handled automatically by the common client)Create
src/korea_public_data_mcp/tools/foo_tools.py— wrap the client function with the@mcp.tool()decorator, catchMissingApiKeyErrorand return a guidance message, cache withcached_callAdd one line
foo_tools.register(mcp)insrc/korea_public_data_mcp/server.pyAdd entries to
.env.exampleand 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 toolsdart_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
Scored across 13 tools
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.
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.
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.
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
Korean company facts in English for AI agents: ~830 KOSPI-listed companies (DART profiles, KRW financials, recent filings) and ~110,000 corporate public procurement suppliers (12-month KONEPS contract awards), plus live National Tax Service business status checks. 4 tools, keyless, read-only.
Korean fact-verification tools for AI agents: business registration, address, DART, apt prices, laws
Powerful OpenDART API-based Korean corporate disclosure tools for accounting professionals
Korean policy & finance facts with primary-source citations (laws, gov notices) for AI agents
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables Claude to access the Korean Financial Supervisory Service's OpenDART API for corporate filings, financial statements, and disclosures.5-
- AlicenseAqualityDmaintenanceEnables MCP clients like Claude Desktop to search, retrieve, and analyze Korean statistical data from KOSIS OpenAPI.161MIT
- AlicenseAqualityCmaintenanceEnables natural language querying of Korean statistical data from KOSIS, including population, employment, GDP, housing prices, and more, with support for regional and trend analysis.810 npm18MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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