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: OpenDART MCP Server

当前已包含的 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 条目（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，我会从那一项开始继续实现。

许可证

供内部自由使用/修改。