KIS REST API MCP Server

韩国投资证券REST API MCP（Model Context Protocol）

使用MCP工具调用韩国投资证券（KIS）REST API的服务器。提供基于目录的通用工具和常用便利工具，用于国内外股票查询、账户查询和订单相关API。

主要功能

• 基于API目录的调用

- 8组，提供166个REST API - 验证API组/ID、路径、HTTP方法、TR_ID候选项、请求参数 - 提供每个参数的韩文标签、输入指南、示例值和主要代码值 - 完整列表： API_CATALOG.md

• 国内股票

- 查询当前价格、期/日行情、报价、行业指数、基本信息 - 查询余额、投资账户资产情况、可买入金额、可卖出数量 - 查看订单/订单历史记录/可取消更正的订单

• 海外股票

- 美国、日本、中国、香港、越南市场代码支持 - 查询当前价格、余额、签订标准当前余额、各货币的保证金、可购买金额 - 根据市场/买入卖出方向自动选择订单TR_ID

• 运行/操作

- stdio, sse, streamable-http 运输支持 - .env 或基于命令行参数的设置 - 自动补全账号、账号商品代码、认证值 - 基于应用程序密钥和账户类型的令牌缓存 - 默认拒绝未知的请求参数 - 默认阻止订购/更正/取消API

安全默认值

默认情况下，更改帐户状态的API（如订单/更正/取消）将被阻止。

KIS_ENABLE_TRADING=true

只有明确设置了上述值，才会运行状态更改API。如果只使用查询API，请不要设置。

要求

• Python>=3.13
• 紫外线

安装

安装 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"

选择Transport：

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": "
",
      "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客户端在连接服务器时将工具名称、说明和输入模式上传到上下文中。便利工具暴露得越多，对话开始时上下文的使用量就越大，因此可以使用轻量级模式，必要时只暴露三个目录工具。

KIS_MCP_TOOLSET=catalog uv run python server.py

值曝光工具数量曝光工具用途 |---|---:|---|---| | full 15个目录工具+所有便利工具|与现有行为兼容| | catalog | 3个| list-kis-api-specs, get-kis-api-spec, call-kis-api |低上下文使用率|

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数量 |---|---|---:| | auth 认证2| | domestic_stock 国内股票74 | overseas_stock 海外股票34 | domestic_bond 国内债券14 | domestic_futureoption 国内礼品选项20 | overseas_futureoption 海外礼物选项19 | elw | ELW | 1 | | etfetn |ETF/ETN|2|

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

环境变量

名称说明默认值 |---|---|---| | KIS_APP_KEY KIS应用程序密钥-| | KIS_APP_SECRET KIS秘密钥匙-| | KIS_ACCOUNT_TYPE | REAL 或者 VIRTUAL | - | | KIS_CANO 账户前8位-| | KIS_ACNT_PRDT_CD |账户商品代码| 01 | | KIS_TOKEN_FILE |令牌缓存文件| token.json | | KIS_ENABLE_TRADING |激活订购/更正/取消API |禁用| | KIS_MCP_TOOLSET | MCP工具曝光范围（full, catalog) | full | | KIS_MCP_LOG_LEVEL |日志级别| INFO | | MCP_TYPE | stdio, sse, streamable-http | stdio | | MCP_HOST |HTTP/SSE主机| 127.0.0.1 | | MCP_PORT |HTTP/SSE端口| 8000 | | MCP_PATH |HTTP/SSE路径| /mcp |

开发/验证

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

许可证

麻省理工学院