Kiwoom MCP 服务端

关键词

证券API云端工具自动化交易金融数据访问多传输 MCP

使用说明（Markdown 格式）

  • 项目简介

    • 本项目是一款基于 MCP 的服务器端实现，使用 TypeScript 编写，旨在将 키움증권（Kiwoom REST API）提供的账户、行情、下单等功能通过 MCP 标准暴露给 LLM 客户端。服务器支持通过标准输入输出（stdio）或 HTTP 传输与客户端进行 JSON-RPC 异步通信，具备会话管理、能力声明以及多工具注册能力，方便在 Claude Desktop 等环境中实现自然语言驱动的证券查询与交易流程。

  • 主要功能点

    • MCP 协议核心实现：处理 MCP 请求、生成 MCP 响应，支持会话管理与能力声明。
    • 工具集合（12 项）：如获取账户余额、投资组合摘要、存款明细、股票价格与日线图、下单、取消订单、未成交单等，均可通过自然语言调用。
    • 传输协议支持：标准输入输出（stdio）与基于 HTTP 的可流式传输（streamable HTTP），方便本地开发与远程部署。
    • 第三方 API 对接：通过 Kiwoom Open API 的 REST 服务读取或提交交易数据，并具备简单的错误处理和重试机制。
    • 安全与容错：内置令牌管理、token 刷新、401 时自动重试，以及统一的错误文本格式，便于在 LLM 输出中呈现友好信息。

  • 安装步骤（本地运行）

    1. 将仓库代码克隆到本地
    2. 安装依赖并构建项目
    3. 选择传输模式（stdio 或 HTTP）启动 MCP 服务器
    4. 在 Claude Desktop（或任意 MCP 客户端）中添加 MCP 服务器配置

  • 服务器配置（供 MCP 客户端使用，不需要客户端自行实现服务器） 配置示例（简化呈现，按文档描述的字段排列；实际配置请按需求填写具体数值）： { "server_name": "kiwoom", "command": "node", "args": ["/절대경로/kiwoom-mcp/dist/index.js"], "env": { "KIWOOM_APP_KEY": "...", "KIWOOM_SECRET_KEY": "...", "KIWOOM_ACCOUNT_NO": "계좌번호10자리", "KIWOOM_IS_MOCK": "true" } }

    说明：

    • server_name: MCP 客户端在云/本地控制台中用于标识该服务器的名称，便于区分和管理。
    • command: 启动服务器的命令，这里为 node。
    • args: 启动命令的参数，指向打包输出的入口文件（dist/index.js）。
    • env: 运行时环境变量，用于 Kiwoom API 的鉴权与运行模式（如是否为模拟交易、账号等）。 注：以上配置可以按实际部署路径及环境变量调整。仓库自带 README 提供了等效示例，确保 Apollo/Claude Desktop 等客户端能够通过该配置连接到 MCP 服务器。

  • 基本使用方法

    1. 启动本地/远程 MCP 服务器（根据环境选择 stdio 或 HTTP 传输）
    2. 在 Claude Desktop 等 MCP 客户端中添加服务器，使用上述配置启动命令
    3. 通过自然语言向 LLM 提出请求，例如查询余额、查看股票价格、下单等
    4. MCP 服务器将解析请求、调用 Kiwoom API 获取结果，并以统一的文本格式返回给 LLM
    5. 如遇错误，驱动文本将给出友好错误信息，方便进行调试或重试

  • 运行与测试要点

    • 请先启用 Kiwoom 的模拟交易环境（KIWOOM_IS_MOCK=true），确保在测试阶段不会进行实际资金交易。
    • 确保 Kiwoom OpenAPI 的 APP KEY、SECRET KEY 与账户号按规定填写，并且服务器所在 IP 已在 API 授权中登记。
    • 生产环境下务必妥善管理 API 密钥与账户信息的安全性。

服务器信息

访问项目