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

这是一个使用韩国投资证券(KIS)的REST API进行股票交易和查询行情信息的MCP（模型上下文协议）服务器。它提供了国内及海外股票交易、行情查询、账户管理等多种金融服务功能。

✨ 主要功能

• 🇰🇷 国内股票交易

  • 实时股价查询
  • 买入/卖出订单
  • 查询余额
  • 查看报价信息
  • 查询订单记录

• 🌏 海外股票交易

  • 支持美国、日本、中国、香港、越南等主要市场
  • 实时股价查询
  • 买入/卖出订单

• ⚡ 特点

  • 异步处理实现快速响应
  • 实时行情及成交信息
  • 稳健的错误处理
  • 可扩展的设计

⚠️ 注意事项

本项目仍处于开发阶段，尚未完成。在实际投资前，请确保进行了充分测试。

• 使用本项目产生的一切损失与责任完全由用户承担。
• 在使用API时必须遵守韩国投资证券的服务条款。
• 对于真实账户的使用需要特别小心，并建议先通过模拟账户进行充分测试。
• 请务必确认有关API调用限制的相关约束条件。

Requirements

• Python >= 3.13
• uv (Python打包工具)

安装

# 1. Install uv if not already installed
pip install uv

# 2. Create and activate virtual environment
uv venv
source .venv/bin/activate  # Linux/MacOS
# or
.venv\\Scripts\\activate  # Windows

# 3. Install dependencies
uv pip install -e .

# 4. Set environment variables
export KIS_APP_KEY="앱키"
export KIS_APP_SECRET="시크릿키"
export KIS_ACCOUNT_TYPE="VIRTUAL"  # 또는 "REAL"
export KIS_CANO="계좌번호"

功能

国内股票交易

• inquery_stock_price - 股票当前价格查询

  • symbol: 股票代码 (例如: "005930") (字符串, 必填)
  • 返回: 当前价格, 涨跌幅, 成交量等信息

• order_stock - 股票买入/卖出订单

  • symbol: 股票代码 (字符串, 必填)
  • quantity: 订单数量 (数字, 必填)
  • price: 订单价格 (0: 市价) (数字, 必填)
  • order_type: 订单类型 ("buy" 或 "sell") (字符串, 必填)

• inquery_balance - 账户余额查询

  • 返回: 持有股票, 评估金额, 盈亏状况等

• inquery_order_list - 按日查询订单列表

  • start_date: 查询开始日期 (YYYYMMDD) (字符串, 必填)
  • end_date: 查询结束日期 (YYYYMMDD) (字符串, 必填)

• inquery_order_detail - 查询订单详情

  • order_no: 订单编号 (字符串, 必填)
  • order_date: 订单日期 (YYYYMMDD) (字符串, 必填)

• inquery_stock_ask - 查询报价信息

  • symbol: 股票代码 (字符串, 必填)
  • 返回: 卖出/买入报价, 报价数量等

海外股票交易

• order_overseas_stock - 海外股票买入/卖出订单

  • symbol: 股票代码 (例如: "AAPL") (字符串, 必填)
  • quantity: 订单数量 (数字, 必填)
  • price: 订单价格 (数字, 必填)
  • order_type: 订单类型 ("buy" 或 "sell") (字符串, 必填)
  • market: 市场代码 (字符串, 必填)
    • "NASD": 纳斯达克
    • "NYSE": 纽约
    • "AMEX": 美国交易所
    • "SEHK": 香港
    • "SHAA": 上海
    • "SZAA": 深圳
    • "TKSE": 东京
    • "HASE": 河内
    • "VNSE": 胡志明市

• inquery_overseas_stock_price - 海外股票当前价格查询

  • symbol: 股票代码 (字符串, 必填)
  • market: 市场代码 (字符串, 必填)

资源

配置

通过环境变量设置API密钥和账户信息：

• KIS_APP_KEY: 韩国投资证券应用密钥
• KIS_APP_SECRET: 韩国投资证券秘密密钥
• KIS_ACCOUNT_TYPE: 账户类型 ("REAL" 或 "VIRTUAL")
• KIS_CANO: 账户号码

交易时间

国内股票：

• 正常交易时间: 09:00 ~ 15:30
• 盘后固定价格交易: 15:40 ~ 16:00

海外股票：

• 美国(纳斯达克/纽约): 22:30 ~ 05:00 (韩国时间)
• 日本: 09:00 ~ 15:10
• 中国: 10:30 ~ 16:00
• 香港: 10:30 ~ 16:00
• 越南: 11:15 ~ 16:15

错误处理

API调用过程中可能出现的主要错误包括：

• 认证错误：如果API密钥或秘密密钥不正确

• 余额不足：当订单金额超过账户余额时

• 时间限制：非交易时段

• 订单限制：订单数量或金额超出限制

• 可扩展的设计

• 通过异步处理实现快速响应

• 实时行情及成交信息

• 稳定的错误处理

License

MIT License