korea-public-data-mcp
korea-public-data-mcp
这是一个让 Claude 直接调用韩国公共数据(金融监督院 OpenDART、韩国银行 ECOS、统计厅 KOSIS、公共数据门户)的 MCP 服务器,能够基于实际 API 响应(而不是猜测)回答财务、经济、统计数值。
与通过接入 DART 电子公示数据来回答财务报表问题的 MCP 相同的方式,对于“这家公司去年的销售额是多少?”、“告诉我最近的基准利率走势”、“我们国家的失业率是百分之几?”等问题,Claude 会调用这个服务器的工具,以最新数值为依据作答。
名称暂定为
korea-public-data-mcp。上传到 GitHub 时可以随意改成想要的名字,不会影响代码运行。
为什么这样设计(设计原则)
设计时遵循了您提出的三项约束。
无 LLM/外部费用 — 这个服务器只是“获取”数据。内部不调用任何 LLM,也不使用付费 API。实际推理/总结由调用这个 MCP 的 Claude 完成,所以服务器运营成本实际上为 0 韩元(不含电费/服务器资源)。
防止 API 封锁(IP 封禁) — 政府公共 API 如果超过每秒/每日调用限制,有时会被临时封锁。因此:
在所有 API 调用的最前面加上每秒调用次数限制(令牌桶),自行放慢请求速度。
相同的提问会通过内存缓存复用;对于 DART 公司列表这类较大的静态文件,则通过磁盘缓存(默认 7 天)避免重复下载。
不按会计科目/期间逐项单独调用,而是以表为单位、按期间范围一次获取(例如:财务报表每家公司一次调用取回全部会计科目;统计则一次查询开始~结束期间)。
对于支持批量查询的 API(如营业执照状态查询),将最多 100 条合并为一次调用发送。
遇到 429/5xx 响应时,使用指数退避最多重试 3 次。
各自用 Docker 运行 — 不启动单独服务器,而是团队成员各自在本地通过
docker build+docker run启动,连接到自己的 Claude。
Related MCP server: korean-stat-mcp
当前已包含的 API(第一阶段核心范围)
如果一次性把全部需求清单(40 多个)都实现,维护起来会比较困难,因此先完整实现了您最常查询的核心 4 家机构。其余的可按照 扩展指南 用同样的模式继续添加。
机构 | 提供的工具 | 备注 |
金融监督院 OpenDART |
| 按公司名称搜索 → corp_code → 财务报表/公示顺序使用 |
韩国银行 ECOS |
| 基准利率/汇率/GDP/物价可按名称直接查询 |
统计厅 KOSIS |
| 关键词搜索后,按表单位批量查询期间范围 |
公共数据门户 (data.go.kr) |
| 营业执照状态支持批量(最多 100 条),其他服务暂时用通用 GET 工具应对 |
韩国进出口银行 |
| 不是 data.go.kr,而是从 koreaexim.go.kr 自己的网站签发。汇率/贷款利率/国际利率是独立的 API 商品,因此需要按服务分别申请并获取 3 个 authkey。营业日 11 点之前/非营业日查询时,数据可能为空 |
API 密钥申请指南
即使还没有拿到密钥,服务器也能正常启动,工具列表也会显示。不过,实际调用工具时,会返回缺少以下密钥的提示信息,请按需要的顺序依次申请。
机构 | 申请处 | 备注 |
OpenDART | https://opendart.fss.or.kr → 注册会员 → [认证密钥申请/管理] | 注册后立即发放,最快 |
ECOS | Open API 认证密钥申请,即时~1 天内 | |
KOSIS | “OpenAPI 使用申请”,审批可能需要一些时间 | |
公共数据门户 | https://www.data.go.kr → 所需服务详情页 → [使用申请] | 需要按服务分别申请。建议先申请“国税厅_营业执照信息真伪确认及状态查询” |
韩国进出口银行 | https://www.koreaexim.go.kr/ir/HPHKIR019M01 → Open API 规范 → 认证密钥发放申请 | 不是通过 data.go.kr,而是 koreaexim.go.kr 自行发放。即时~当天 |
拿到密钥后,请将 .env.example 复制为 .env 并填写。
cp .env.example .env
# .env 파일을 열어 발급받은 키 입력快速开始(Docker)
git clone <이 레포 주소>
cd korea-public-data-mcp
cp .env.example .env # 키 채워넣기 (없어도 일단 진행 가능)
docker build -t korea-public-data-mcp .在 Claude Desktop / Claude Code 的 MCP 配置(如 claude_desktop_config.json)中按如下方式注册。
{
"mcpServers": {
"korea-public-data": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--env-file", "/절대경로/korea-public-data-mcp/.env",
"korea-public-data-mcp"
]
}
}
}重启 Claude 后,工具列表中会出现 dart_*、ecos_*、kosis_*、data_go_kr_* 等工具。现在,当您问“三星电子 2023 年销售额是多少?”这类问题时,Claude 会调用这些工具,并根据实际数值回答。
本地(不使用 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로 종료)扩展指南(添加新 API)
您提供的完整清单(RISS、KIPRIS、国家法令信息、国家集市、首尔开放数据广场等)只要按下面的模式重复即可。以添加新机构 foo 为例:
在
src/korea_public_data_mcp/config.py的API_KEYS中添加foo条目(env var、申请 URL)编写
src/korea_public_data_mcp/clients/foo.py— 使用core/http_client.get_json只编写实际端点调用逻辑(重试/速率限制由公共客户端自动处理)编写
src/korea_public_data_mcp/tools/foo_tools.py— 用@mcp.tool()装饰器包装 client 函数,捕获MissingApiKeyError后返回提示消息,并用cached_call做缓存在
src/korea_public_data_mcp/server.py中添加一行foo_tools.register(mcp)在
.env.example、README 表格中添加条目
这种结构使得即使新增 API,也无需每次重新编写防封锁(速率限制/缓存/批量)逻辑。
下一步扩展候选(按您的需求清单)
法律/行政:国家法令信息 Open API、开放国会信息 API
采购/事业:国家集市(g2b)、采购数据枢纽、NTIS 国家科学技术信息
学术:RISS、KISTI、国立中央图书馆 OpenAPI
知识产权:KIPRIS Plus(专利·商标)
地区:首尔开放数据广场、京畿数据梦想
告诉我优先级或下一个要接入的 API,我会从那一项开始继续实现。
许可证
供内部自由使用/修改。
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