Korea Data MCP

korea-data-mcp

English | 한국어

直接把韩国公共 API 交给 AI Agent，它很容易答错。korea-data-mcp 能给出正确答案。

一个 MCP 服务，接入 OpenDART、data.go.kr 和 law.go.kr 提供的官方免费 API，涵盖韩国企业披露和财务数据、股价、公寓成交价、企业注册状态、公共假日、法规和法院判决。

• 准确，并有证据支撑。 我们在实际 API 中发现了 47 个陷阱（半年度营收错误、尚未生效的法律、已取消的交易、2026 年变更的区划代码等），并逐一处理，每个陷阱都由使用真实响应的测试覆盖。完整列表公开可查：korea-data-mcp 为你处理的问题。
• 一键安装。 单个二进制文件，无需安装其他内容。在 Claude Desktop 中打开 korea-data-mcp.mcpb 并输入密钥。也收录于 MCP 官方注册表。
• 保护隐私。 它在你的设备上运行。你的密钥和问题只会发送到政府 API，不会经过任何第三方服务，也不会收集遥测数据。
• 专注实用。 提供 15 个描述清晰的工具，让 Agent 无需在上下文中塞入几十个其他工具，也能选对工具。

为什么重要

示例：“Samsung Electronics 在 2025 年上半年的营收是多少？”这是 OpenDART 实际返回的内容：

{ "account_nm": "매출액", "thstrm_dt": "2025.01.01 ~ 2025.06.30",
  "thstrm_amount": "74,566,317,000,000", "thstrm_add_amount": "153,706,820,000,000" }

期间显示为 1 月至 6 月，因此 Agent 会读取 thstrm_amount 并回答 74.6 万亿韩元。这是错的：它只代表第二季度。半年度数据 153.7 万亿韩元位于另一个字段。大多数韩国 MCP 服务会原样传递此响应。korea-data-mcp 返回：

{ "name": "매출액", "statement_type": "income_statement",
  "current_period": "2025-01-01 ~ 2025-06-30",
  "current_amount": 153706820000000, "current_quarter_amount": 74566317000000 }

这样 Agent 就能答对，甚至还能拆分出第二季度的数据：

另外还有三个会悄无声息地导致错误答案的陷阱：

• 尚未生效的法律。 向 law.go.kr 查询当前的《劳动基准法》（근로기준법）时，返回的文本包含 제44조의4，并标注为自 2026-10-08 起生效。实际上，它要到 2027-01-01 才生效；官方的“现行法律”文本已经包含仅公布、尚未生效的修正内容。korea-data-mcp 会返回你所查询日期（默认为今天）有效的文本，并在 upcoming 中列出即将生效的内容（工具输出已缩短）：

  

• 从未发生的交易。 公寓交易数据会保留已取消的交易，只用一个标志标记：2025 年 9 月，江南区 233 笔交易中有 12 笔已取消，其中包括一笔 75 亿韩元的交易。把这些交易计入平均值会导致错误。korea-data-mcp 会将其排除。

• 悄然失效的代码。 2026 年，光州广域市和全罗南道合并，华城市拆分为四个区，仁川也重新划分了区。大多数代码表仍列出的旧区划代码如今会返回零笔交易，连过去月份的数据也不例外。使用 korea-data-mcp 时，Agent 只需说 광주 북구 或 화성시。

还有更多问题：以 HTTP 200 返回的错误、与当前记录混杂的过期记录、带连字符书写时会查询失败的企业注册号、因公司更名而拆分的股价历史，以及 Go 中会失败的 TLS 握手。查看全部 47 个问题：korea-data-mcp 为你处理的问题。

你可以询问什么

将 korea-data-mcp 连接到 Claude（或任何 MCP 客户端），然后用英语或韩语提问：

• “三星电子 2025 年上半年的营收是多少？最近披露了什么信息？”
• “2025 年 9 月，분당구 的公寓成交中位价是多少？”
• “《劳动基准法》（근로기준법）第 44 条之 4 已经生效了吗？”
• “查找近期有关不当解雇（부당해고）的最高法院裁决，并总结最新裁决的判决要点。”
• “企业注册号 124-81-00998 目前仍然有效吗？”
• “NAVER 的股价上个月走势如何？”
• “韩国今年还剩下哪些公共假日？”

来源	涵盖内容	密钥
OpenDART（전자공시）	约 120,000 家公司的企业简介、披露信息和财务报表	OPENDART_API_KEY
data.go.kr（공공데이터포털）	节假日、法人信息、企业状态、公寓交易、股价	DATAGOKR_SERVICE_KEY
law.go.kr（국가법령정보）	任意日期生效的法规、法院裁决	LAWGOKR_OC

这三个密钥都可免费获取。你可以先使用其中一个。

快速开始

**Claude Desktop，一键安装：**下载 korea-data-mcp.mcpb，打开它（或将其拖入“设置” →“扩展”），然后输入你已有的密钥（获取方式）。无需安装其他内容；直接跳到步骤 4。

1. 安装

从 Releases 下载适用于 macOS、Linux 或 Windows（Intel 或 ARM）的二进制文件，解压后记下 korea-data-mcp 的绝对路径（Windows 上为 korea-data-mcp.exe）。例如，在 Apple Silicon Mac 上：

curl -L https://github.com/YoungsoonLee/korea-data-mcp/releases/latest/download/korea-data-mcp_darwin_arm64.tar.gz | tar xz
./korea-data-mcp -version

在 macOS 上，通过浏览器下载的二进制文件会因来自未识别的开发者而遭到阻止；运行一次 xattr -d com.apple.quarantine korea-data-mcp 即可。通过 curl 下载不受影响。

或者使用 Go 1.26 或更高版本（Go 1.21+ 会自动下载正确的工具链）：

go install github.com/YoungsoonLee/korea-data-mcp/cmd/korea-data-mcp@latest

二进制文件会安装到 $(go env GOPATH)/bin/korea-data-mcp。

2. 获取密钥

建议从 OpenDART 开始：在 opendart.fss.or.kr 注册，申请密钥（인증키 신청），申请后即可获得。三个密钥的获取步骤及对应的韩语菜单名称，请参阅：获取 API 密钥。任意组合均可使用；缺少密钥的工具不会提供。

你在韩国境外吗？这些门户通常要求进行韩国身份验证（韩国手机号码）才能注册，因此从境外获取密钥可能很困难，甚至无法实现。我们计划推出无需自备密钥的托管版本：加入候补名单。

3. 连接客户端

请使用绝对路径。没有的密钥可以省略。

Claude Code：

claude mcp add korea-data-mcp \
  -e OPENDART_API_KEY=... \
  -e DATAGOKR_SERVICE_KEY=... \
  -e LAWGOKR_OC=... \
  -- /absolute/path/to/korea-data-mcp

**Claude Desktop：**编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），然后重启 Claude Desktop：

{
  "mcpServers": {
    "korea-data-mcp": {
      "command": "/absolute/path/to/korea-data-mcp",
      "env": {
        "OPENDART_API_KEY": "...",
        "DATAGOKR_SERVICE_KEY": "...",
        "LAWGOKR_OC": "..."
      }
    }
  }
}

其他 MCP 客户端使用相同的命令和环境变量。

如果要将密钥统一保存在一个文件中，请将 .env.example 复制为 .env，填写内容，然后将 -env-file /absolute/path/to/.env 作为参数传入。环境中设置的变量优先于文件中的变量。

4. 检查

向你的 Agent 提问：“启用了哪些 korea-data-mcp 提供方？”它会调用 hub_list_providers，列出已启用的提供方以及缺少的密钥。然后试试上面的任意一个问题。

API 密钥

分步说明和故障排查：获取 API 密钥。这三种密钥均免费，但注册通常需要通过韩国身份验证。如果无法获取，请加入托管版候补名单。

环境变量	来源	获取方式
OPENDART_API_KEY	OpenDART	opendart.fss.or.kr → 인증키 신청（申请密钥）
DATAGOKR_SERVICE_KEY	data.go.kr	data.go.kr → 注册 → 为每个 API 申请（활용신청；链接见 工具） → My Page
LAWGOKR_OC	law.go.kr	open.law.go.kr → OPEN API 신청（申请） → 마이페이지 → API인증키관리（OC）

data.go.kr：该门户会发放两种密钥：Encoding 和 Decoding。请使用 Decoding 密钥。Encoding 密钥会被重复进行 URL 编码，导致 SERVICE_KEY_IS_NOT_REGISTERED_ERROR 错误。一个密钥适用于你申请的所有 API。

law.go.kr：OC 是你在 마이페이지 → API인증키관리 中自行选择的值。OC 错误会导致“사용자 정보 검증에 실패하였습니다”错误。law.go.kr 会在返回的每个链接中加入 OC，因此不要将其他密钥用作 OC（korea-data-mcp 不会传递这些链接）。

工具

OpenDART（OPENDART_API_KEY）

工具	功能
opendart_search_companies	按韩文/英文名称、股票代码或 corp_code 查找公司的 corp_code
opendart_get_company	公司简介（기업개황）：CEO、市场、注册编号、地址、财年结束日期
opendart_search_disclosures	按公司、日期范围、类型和市场搜索披露信息（공시）
opendart_get_financials	指定年度和报告的主要财务科目（주요계정），并提供与前期的比较

所有接受 corp_code 的 OpenDART 工具也接受 6 位股票代码（例如 005930）。

data.go.kr（DATAGOKR_SERVICE_KEY）。每个 API 都需要在 data.go.kr 上单独申请（활용신청）；申请链接如下。

工具	功能	申请的 API
datagokr_list_holidays	按年或月查询公共假日（공휴일），包括补休、春节、中秋节和选举日，并提供英文名称和星期几。还包括纪念日、24 节气和季节性日子。数据范围为 2004 年至未来两年	韩国天文研究院_特殊日信息
datagokr_search_corporations	按名称查找韩国法人，无论是否上市。返回法人注册号（crno）；对于 DART 报告对象，还会返回供 opendart 工具使用的 dart_corp_code	金融委员会_企业基本信息
datagokr_get_corporation	当前公司简介：CEO、市场、注册编号、成立和上市日期、地址、行业、员工人数、平均任职年限和薪酬、审计师及审计意见	同上
datagokr_check_business_status	使用国税厅数据核验最多 100 个营业执照号码（사업자등록번호）：是否已注册、营业状态（正常、暂停或关闭，并提供日期）以及增值税类型。可使用连字符	国税厅_营业执照信息真伪核验及状态查询
datagokr_list_apartment_trades	按地区和月份查询公寓销售交易，按时间从新到旧排列，并提供价格中位数/最低价/最高价摘要。价格单位为 KRW；默认排除已取消的交易；可按公寓名称或社区筛选。地区可以是名称（강남구、서울 중구、분당구、광주 북구）或 5 位代码；对于设有区的城市，例如 수원시 或 화성시，查询范围涵盖其所有区	国土交通部_公寓买卖实际交易价数据
datagokr_get_stock_prices	查询 KOSPI、KOSDAQ 或 KONEX 股票的每日价格：收盘价、涨跌额、开盘价/最高价/最低价、成交量、成交额和市值。股票可使用名称（삼성전자、naver）、6 位代码或 ISIN；历史记录会在更名后继续沿用该代码。数据自 2020 年起	金融委员会_股票行情信息

law.go.kr（LAWGOKR_OC）

工具	功能
lawgokr_search_laws	按名称或官方简称（민법、중대재해처벌법）搜索现行法规（法律、总统令、条例），也可通过 in_text 按条文内容搜索。精确匹配和法律优先
lawgokr_get_law	获取法规在某日期生效时的文本（默认为今天），可获取全文或单条（제50조、43의2），包括款、项和目。upcoming 中会列出已公布但尚未生效的修正案；as_of 支持任何过去或未来日期
lawgokr_search_precedents	按案件名称、全文、案号（2020다296604，可包含空格）、法院和判决日期搜索法院裁判（판례），按时间从新到旧排列。默认仅搜索法院记录，因此所有结果均可读取
lawgokr_get_precedent	按 ID 或案号获取裁判：争点（판시사항）、裁判要旨（판결요지）、引用的法规和案例，以及通过 include_full_text 获取的完整裁判文书

Hub：hub_list_providers 会列出已启用的提供方和缺少的密钥。

安全性、限制与数据新鲜度

• 你的密钥会留在本机。 korea-data-mcp 在本地运行，并且只会将每个密钥发送给签发该密钥的服务。不会收集遥测数据。错误消息不会包含密钥或查询字符串。
• HTTP 模式没有身份验证。 -http 会向所有能够访问该端口的人提供这些工具，并使用你的密钥。除非前面有经过身份验证的代理，否则请绑定到 localhost（-http 127.0.0.1:8080）。默认的 stdio 模式不会开放端口。
• 上游配额仍然适用。 data.go.kr 开发者账号的每个 API 每天允许调用 10,000 次；OpenDART 和 law.go.kr 也有各自的限制。korea-data-mcp 会缓存响应 10 分钟，并缓存 DART 公司列表 24 小时。
• 数据的新鲜度取决于来源。 公寓交易最晚可能在合同签订后 30 天才上报，因此最新月份的数据会逐渐补齐。股票价格按日提供，并在每个交易日结束后更新。

路线图

• OpenDART：公司、披露、财务数据
• data.go.kr：节假日、法人信息、经营状态、公寓交易、股票价格
• law.go.kr：法规、法院裁决
• 韩国银行 ECOS、KOSIS（韩国统计信息服务）
• 面向日本的姊妹服务，首先支持 EDINET（企业披露）

想要新增数据源？提交申请。发现 API 行为异常？提交 issue。没有韩国 API 密钥？加入托管服务候补名单。如需构建、测试或添加提供方，请参阅 docs/DEVELOPMENT.md。

许可证

Apache License 2.0。工具返回的数据来自上游服务，并受其使用条款约束。