韩国投资证券 REST API MCP (Model Context Protocol)

这是一个将韩国投资证券 (KIS) REST API 作为 MCP 工具调用的服务器。它提供基于目录的通用工具和常用便捷工具，用于查询国内/海外股票、账户信息及订单相关 API。

主要功能

• 基于 API 目录的调用

  • 提供 8 个组，共 166 个 REST API

  • 可确认 API 组/ID、路径、HTTP 方法、TR_ID 候选值及请求参数

  • 提供各参数的韩文标签、输入指南、示例值及主要代码值

  • 完整列表: API_CATALOG.md

• 国内股票

  • 查询当前价格、期间/每日行情、报价、行业指数、基本信息

  • 查询余额、投资账户资产状况、可买入金额、可卖出数量

  • 查询订单/订单记录/可更正取消的订单

• 海外股票

  • 支持美国、日本、中国、香港、越南市场代码

  • 查询当前价格、余额、按成交基准的当前余额、各币种保证金、可买入金额

  • 根据市场/买卖方向自动选择订单 TR_ID

• 执行/运行

  • 支持 stdio, sse, streamable-http 传输方式

  • 基于 .env 或命令行参数进行配置

  • 自动补全账号、账户商品代码、认证值

  • 基于 App Key 和账户类型的令牌缓存

  • 默认拒绝未知请求参数

  • 默认拦截订单/更正/取消 API

Related MCP server: kiwoom-mcp

安全默认值

像订单/更正/取消这类会改变账户状态的 API 默认处于拦截状态。

KIS_ENABLE_TRADING=true

仅在明确设置上述值时，状态变更 API 才会执行。如果仅使用查询 API，请勿设置。

要求

• Python >= 3.13

• uv

安装

请参考 INSTALL.md 进行安装。LLM 或 MCP 客户端在配置时也应优先阅读此文件。

INSTALL.md 包含以下内容：

• 基于 uv 的依赖安装

• .env 创建及 KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD 设置

• Codex CLI, Claude Code, Claude Desktop, 通用 MCP 客户端注册示例

• 用于节省上下文的 KIS_MCP_TOOLSET=catalog 设置

• 用于查询余额、可买入金额、当前价格的 call-kis-api 示例

快速本地准备：

pip install uv
uv sync
cp .env.example .env
chmod 600 .env

接着在 .env 中设置以下值。详细的值说明和各客户端注册命令请参考 INSTALL.md。

KIS_APP_KEY="발급받은 앱키"
KIS_APP_SECRET="발급받은 시크릿키"
KIS_ACCOUNT_TYPE="REAL"   # REAL 또는 VIRTUAL
KIS_CANO="계좌번호 앞 8자리"
KIS_ACNT_PRDT_CD="01"
KIS_MCP_TOOLSET="catalog"

运行

# stdio, 로컬 MCP 클라이언트 권장
uv run python server.py

也可以通过命令行参数进行设置。

uv run python server.py \
  --app-key "앱키" \
  --app-secret "시크릿키" \
  --account-type "REAL" \
  --cano "계좌번호" \
  --acnt-prdt-cd "01"

选择传输方式：

MCP_TYPE=stdio uv run python server.py
MCP_TYPE=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run python server.py
MCP_TYPE=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/sse uv run python server.py

MCP 客户端注册示例：

以下是通用 MCP 客户端的最小示例。Codex CLI, Claude Code, Claude Desktop 命令请使用 INSTALL.md。

{
  "mcpServers": {
    "kis-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "<project-root>",
      "env": {
        "KIS_MCP_TOOLSET": "catalog",
        "KIS_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

MCP 工具构成

目录工具

list-kis-api-specs 会同时返回必填参数的标签、示例值及主要代码值。 get-kis-api-spec 会返回所有参数的 label, guide, examples, values, default, auto_fill 信息，以便 LLM 直接确认调用所需的输入格式。

call-kis-api 共同执行以下处理：

• 基于环境变量自动输入账号/账户商品代码

• 发放并缓存认证令牌

• 构建 GET/POST 请求

• 在多个 TR_ID 中自动选择可判定的订单 TR_ID

• 应用状态变更 API 安全门控

• 默认拒绝目录中不存在的参数

便捷工具

常用的国内/海外股票功能也作为单独的 MCP 工具提供。

如果没有 KIS_ENABLE_TRADING=true，订单工具也不会执行。

工具加载优化

MCP 客户端在连接服务器时会将工具名称、说明、输入模式加载到上下文中。暴露的便捷工具越多，对话开始时的上下文占用量就越大，因此在需要时可以使用仅暴露 3 个目录工具的轻量模式。

KIS_MCP_TOOLSET=catalog uv run python server.py

catalog 模式是为了减少 MCP 工具模式加载量而设计的。虽然隐藏了便捷工具，但 166 个 API 仍然可以通过 call-kis-api 调用。需要的 API 可以通过 list-kis-api-specs 查找，所需的详细参数可以通过 get-kis-api-spec 随时查询。

推荐使用流程：

1. 使用 list-kis-api-specs 搜索 API。

2. 使用 get-kis-api-spec 确认必填参数、示例值、代码值。

3. 使用 call-kis-api 调用实际 API。

在 MCP 客户端设置中只需添加环境变量即可。

{
  "env": {
    "KIS_MCP_TOOLSET": "catalog"
  }
}

如果想直接在工具列表中暴露常用便捷工具，请使用默认值 full。

call-kis-api 示例

国内股票当前价：

{
  "group": "domestic_stock",
  "api_type": "inquire_price",
  "params": {
    "fid_cond_mrkt_div_code": "J",
    "fid_input_iscd": "005930"
  }
}

海外股票余额：

{
  "group": "overseas_stock",
  "api_type": "inquire_balance",
  "params": {
    "ovrs_excg_cd": "NASD",
    "tr_crcy_cd": "USD"
  }
}

海外股票成交基准当前余额：

{
  "group": "overseas_stock",
  "api_type": "inquire_present_balance",
  "params": {
    "wcrc_frcr_dvsn_cd": "01",
    "natn_cd": "000",
    "tr_mket_cd": "00",
    "inqr_dvsn_cd": "00"
  }
}

海外股票可买入金额：

{
  "group": "overseas_stock",
  "api_type": "inquire_psamount",
  "params": {
    "ovrs_excg_cd": "NASD",
    "ovrs_ord_unpr": "1",
    "item_cd": "QQQ"
  }
}

主要 API 组

完整的 API ID、路径、TR_ID、必填参数指南整理在 API_CATALOG.md 中。

环境变量

开发/验证

uv run python -m compileall main.py server.py example.py tests
uv run python -m unittest discover -v
git diff --check

许可证

MIT