Ko Stock

ko-stock-mcp

一个 MCP 服务，可向 Claude Desktop 等 MCP 客户端提供韩国 **DART（전자공시시스템，金融监督服务电子披露）**数据。

한국어 문서는 README.ko.md를 참고하세요.

工具

提供 DART（电子披露）和 KRX（韩国交易所）工具。

DART（披露）

工具	说明
get_corp_code	根据公司名称或股票代码（6 位）查询公司的 DART corp_code（8 位）。这是其他工具的入口。
get_company_info	公司简介（名称、CEO、市场类别、行业、成立日期等）。
get_disclosure_list	按公司、日期范围或披露类型搜索披露信息。
get_disclosure	获取披露文件的原文。大型文件会返回目录（toc）；可通过 section_id 深入查看。
get_financial_statement	从定期报告中获取 XBRL 财务报表（BS / IS / CIS / SCE / CF）。
get_today_date	获取 KST/UTC 今日日期（YYYYMMDD + ISO）。

KRX（韩国交易所）——需要 KRX_API_KEY

工具	说明
get_market_type	确定股票代码所属的市场（KOSPI/KOSDAQ/KONEX）。优先使用 DART 公司类别，若无则回退到 KRX。
get_stock_trade_info	获取某个交易日的每日交易数据（收盘价、涨跌幅、成交量、市值等）。
get_stock_base_info	股票基本信息（名称、标准代码/短代码、上市日期、面值、流通股数等）。

典型流程——披露/财务数据：get_corp_code →（get_disclosure_list | get_financial_statement | get_company_info）→ 使用 get_disclosure 获取全文。市场数据： （可选 get_market_type →）get_stock_trade_info | get_stock_base_info（bas_dd 必须为交易日；非交易日将返回空结果）。

未设置 KRX_API_KEY 时，KRX 工具会返回易于理解的错误；DART 功能不受影响。 请注意，get_market_type 只需 DART 密钥即可使用（通过公司类别）。

KRX 响应字段

get_stock_trade_info / get_stock_base_info 会在 result 下原样返回 KRX 字段（金额/数量为字符串，日期格式为 YYYYMMDD）。

get_stock_trade_info（每日交易数据）

字段	含义
BAS_DD	基准日期（YYYYMMDD）
ISU_CD	股票代码（此响应中的 6 位短代码）
ISU_NM	股票名称
MKT_NM	市场（KOSPI/KOSDAQ/KONEX）
SECT_TP_NM	部门/板块
TDD_CLSPRC	收盘价
CMPPREVDD_PRC	与前一日相比的涨跌额
FLUC_RT	涨跌幅（%）
TDD_OPNPRC / TDD_HGPRC / TDD_LWPRC	开盘价 / 最高价 / 最低价
ACC_TRDVOL	累计成交量（股）
ACC_TRDVAL	累计成交额（KRW）
MKTCAP	市值（KRW）
LIST_SHRS	上市股数

get_stock_base_info（股票基本信息）

字段	含义
ISU_CD	标准代码（12 位，例如 KR7005930003）
ISU_SRT_CD	短代码（6 位，例如 005930）
ISU_NM	股票全名
ISU_ABBRV	简称
ISU_ENG_NM	英文名称
LIST_DD	上市日期（YYYYMMDD）
MKT_TP_NM	市场（KOSPI/KOSDAQ/KONEX）
SECUGRP_NM	证券类别（例如普通股）
SECT_TP_NM	部门/板块
KIND_STKCERT_TP_NM	股票类型（例如普通股）
PARVAL	面值
LIST_SHRS	上市股数

get_market_type 返回 { "market": "KOSPI"|"KOSDAQ"|"KONEX", "source": "dart"|"krx"|"cache" } （source 表示分类信息的来源）。

要求

• Python >= 3.10
• uv
• DART Open API 密钥——在 https://opendart.fss.or.kr 注册（免费，即时开通）。
• （可选）KRX Open API 密钥——在 https://openapi.krx.co.kr 注册，申请密钥，然后 申请六项股票服务（3 项每日交易 + 3 项基本信息）；审批约需 1 天。 仅 KRX 市场数据工具需要此密钥。

设置

uv sync
cp .env.example .env   # then put your DART_API_KEY in .env

运行 / 开发

# Launch the MCP Inspector for local testing
uv run mcp dev src/ko_stock_mcp/server.py

# Or run the server directly (stdio)
uv run ko-stock-mcp

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "ko-stock-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ko-stock-mcp", "run", "python", "-m", "ko_stock_mcp.server"]
    }
  }
}

uv --directory 会以此项目作为工作目录运行服务，因此会自动加载 .env （其中包含 DART_API_KEY，以及可选的 KRX_API_KEY）——无需在此处重复配置这些密钥。如果你愿意，也可以显式传入这些密钥：

"env": { "DART_API_KEY": "<YOUR_DART_API_KEY>", "KRX_API_KEY": "<YOUR_KRX_API_KEY>" }

在 macOS 上，配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json。编辑后重启 Claude Desktop。

许可证

MIT——详见 LICENSE。