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

korea-public-data-mcp

korea-public-data-mcp

这是一个让 Claude 直接调用韩国公共数据(金融监督院 OpenDART、韩国银行 ECOS、统计厅 KOSIS、公共数据门户)的 MCP 服务器,能够基于实际 API 响应(而不是猜测)回答财务、经济、统计数值。

与通过接入 DART 电子公示数据来回答财务报表问题的 MCP 相同的方式,对于“这家公司去年的销售额是多少?”、“告诉我最近的基准利率走势”、“我们国家的失业率是百分之几?”等问题,Claude 会调用这个服务器的工具,以最新数值为依据作答。

名称暂定为 korea-public-data-mcp。上传到 GitHub 时可以随意改成想要的名字,不会影响代码运行。

为什么这样设计(设计原则)

设计时遵循了您提出的三项约束。

  1. 无 LLM/外部费用 — 这个服务器只是“获取”数据。内部不调用任何 LLM,也不使用付费 API。实际推理/总结由调用这个 MCP 的 Claude 完成,所以服务器运营成本实际上为 0 韩元(不含电费/服务器资源)。

  2. 防止 API 封锁(IP 封禁) — 政府公共 API 如果超过每秒/每日调用限制,有时会被临时封锁。因此:

    • 在所有 API 调用的最前面加上每秒调用次数限制(令牌桶),自行放慢请求速度。

    • 相同的提问会通过内存缓存复用;对于 DART 公司列表这类较大的静态文件,则通过磁盘缓存(默认 7 天)避免重复下载。

    • 不按会计科目/期间逐项单独调用,而是以表为单位、按期间范围一次获取(例如:财务报表每家公司一次调用取回全部会计科目;统计则一次查询开始~结束期间)。

    • 对于支持批量查询的 API(如营业执照状态查询),将最多 100 条合并为一次调用发送。

    • 遇到 429/5xx 响应时,使用指数退避最多重试 3 次。

  3. 各自用 Docker 运行 — 不启动单独服务器,而是团队成员各自在本地通过 docker build + docker run 启动,连接到自己的 Claude。

Related MCP server: korean-stat-mcp

当前已包含的 API(第一阶段核心范围)

如果一次性把全部需求清单(40 多个)都实现,维护起来会比较困难,因此先完整实现了您最常查询的核心 4 家机构。其余的可按照 扩展指南 用同样的模式继续添加。

机构

提供的工具

备注

金融监督院 OpenDART

dart_search_company, dart_get_financial_statements, dart_get_company_disclosures

按公司名称搜索 → corp_code → 财务报表/公示顺序使用

韩国银行 ECOS

ecos_get_key_indicator, ecos_search_statistics, ecos_get_statistic_data

基准利率/汇率/GDP/物价可按名称直接查询

统计厅 KOSIS

kosis_search_statistics, kosis_get_statistics_data

关键词搜索后,按表单位批量查询期间范围

公共数据门户 (data.go.kr)

data_go_kr_check_business_status, data_go_kr_generic_get

营业执照状态支持批量(最多 100 条),其他服务暂时用通用 GET 工具应对

韩国进出口银行

koreaexim_get_exchange_rates, koreaexim_get_loan_rates, koreaexim_get_international_rates

不是 data.go.kr,而是从 koreaexim.go.kr 自己的网站签发。汇率/贷款利率/国际利率是独立的 API 商品,因此需要按服务分别申请并获取 3 个 authkey。营业日 11 点之前/非营业日查询时,数据可能为空

API 密钥申请指南

即使还没有拿到密钥,服务器也能正常启动,工具列表也会显示。不过,实际调用工具时,会返回缺少以下密钥的提示信息,请按需要的顺序依次申请。

机构

申请处

备注

OpenDART

https://opendart.fss.or.kr → 注册会员 → [认证密钥申请/管理]

注册后立即发放,最快

ECOS

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

Open API 认证密钥申请,即时~1 天内

KOSIS

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

“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 为例:

  1. 在 src/korea_public_data_mcp/config.py 的 API_KEYS 中添加 foo 条目(env var、申请 URL)

  2. 编写 src/korea_public_data_mcp/clients/foo.py — 使用 core/http_client.get_json 只编写实际端点调用逻辑(重试/速率限制由公共客户端自动处理)

  3. 编写 src/korea_public_data_mcp/tools/foo_tools.py — 用 @mcp.tool() 装饰器包装 client 函数,捕获 MissingApiKeyError 后返回提示消息,并用 cached_call 做缓存

  4. 在 src/korea_public_data_mcp/server.py 中添加一行 foo_tools.register(mcp)

  5. 在 .env.example、README 表格中添加条目

这种结构使得即使新增 API,也无需每次重新编写防封锁(速率限制/缓存/批量)逻辑。

下一步扩展候选(按您的需求清单)

  • 法律/行政:国家法令信息 Open API、开放国会信息 API

  • 采购/事业:国家集市(g2b)、采购数据枢纽、NTIS 国家科学技术信息

  • 学术:RISS、KISTI、国立中央图书馆 OpenAPI

  • 知识产权:KIPRIS Plus(专利·商标)

  • 地区:首尔开放数据广场、京畿数据梦想

告诉我优先级或下一个要接入的 API,我会从那一项开始继续实现。

许可证

供内部自由使用/修改。

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