korea-public-data-mcp

这是一个MCP服务器，让Claude可以直接调用大韩民国公共数据（金融监督院OpenDART、韩国银行ECOS、统计厅KOSIS、公共数据门户），基于实际API响应而非猜测来回答财务、经济、统计数值问题。

与使用DART电子公示数据回答财务报表问题的MCP相同的方式，对于"这家公司去年销售额是多少？"、"告诉我最近基准利率趋势"、"我们国家的失业率是百分之几？"等问题，Claude会调用此服务器的工具，基于最新数值来回答。

名称暂定为korea-public-data-mcp。上传到GitHub时，即使更改为您想要的名称，代码运行也不受影响。

为什么这样设计（设计原则）

按照负责人提出的三个约束条件进行了设计。

1. 无LLM/外部费用 — 此服务器仅"获取"数据。内部不调用任何LLM，也不使用付费API。实际的推理/摘要由调用此MCP的Claude完成，因此服务器运营成本实际上为零（电费/服务器资源除外）。

2. 防止API封锁（IP封禁） — 政府公共API在超过每秒/每日调用限制时，有时会被暂时封锁。因此：

   • 在所有API调用前端设置每秒调用次数限制（令牌桶），自行降低速度。

   • 重复相同问题时，使用内存缓存重复使用，像DART公司列表这样的大型静态文件，通过磁盘缓存（默认7天）防止重新下载。

   • 不逐个单独调用会计科目/期间，而是按表格单位·期间范围单位一次性获取（例如：财务报表每家公司调用1次获取全部会计科目，统计信息一次性查询开始~结束期间）。

   • 对于支持批处理的API（如营业执照状态查询），最多将100条合并为一次调用发送。

   • 对于429/5xx响应，使用指数退避最多重试3次。

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

当前包含的API（第一阶段核心范围）

如果一次性实现全部请求列表（约40个），维护范围会变得困难，因此首先完整实现了负责人最常查找的4个核心机构。其余部分可以按照扩展指南的相同模式继续添加。

API密钥发放指南

即使尚未获得密钥，服务器也能正常启动并显示工具列表。但实际调用工具时会返回缺少密钥的提示信息，请按需依次申请。

收到密钥后，将.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项（环境变量、发放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()装饰器包装客户端函数，捕获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，我将从该项目开始继续实现。

许可证

可自由用于内部使用/修改。