技术文档摘要

IBKR MCP 服务器

基于FastMCP 2.0和MCP StreamableHTTP实现的Interactive Brokers (IBKR) MCP服务器，提供账户管理、交易操作和市场数据查询功能。

特性

• 🔗 连接管理：与IBKR TWS/Gateway的稳定连接
• 📊 账户信息：查询账户概要、持仓和余额
• 💹 交易操作：下单、撤单、查询订单状态
• 📈 市场数据：实时和历史市场数据检索
• 🛡️ 类型安全：使用Pydantic进行数据验证
• ⚡ 异步架构：高性能异步I/O操作
• 📝 丰富的日志记录：结构化日志
• 🔧 灵活配置：支持环境变量和配置文件

安装

从源代码安装

git clone https://github.com/yourusername/ibkr-mcp-server.git
cd ibkr-mcp-server

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装包
pip install -e .

开发环境设置

# 安装开发依赖
pip install -e ".[dev]"

# 设置预提交钩子
pre-commit install

快速开始

1. 配置环境

在项目根目录创建一个.env文件：

# MCP服务器设置
MCP__HOST=0.0.0.0
MCP__PORT=8080

# IBKR连接设置
IBKR__HOST=127.0.0.1
IBKR__PORT=4002
IBKR__CLIENT_ID=1
IBKR__READONLY=false

# 日志设置
LOGGING__LEVEL=INFO

2. 测试连接

# 测试IBKR连接
python -m ibkr_mcp_server.cli test --host 127.0.0.1 --port 4002

3. 启动服务器

# 启动服务器
python -m ibkr_mcp_server.cli serve

# 或者使用自定义参数
python -m ibkr_mcp_server.cli serve --host 0.0.0.0 --port 8080

配置

环境变量

变量	默认值	描述
MCP__HOST	0.0.0.0	MCP服务器监听地址
MCP__PORT	8080	MCP服务器端口
IBKR__HOST	127.0.0.1	IBKR TWS/Gateway地址
IBKR__PORT	4002	IBKR TWS/Gateway端口
IBKR__CLIENT_ID	1	IBKR客户端ID
IBKR__READONLY	false	只读模式
LOGGING__LEVEL	INFO	日志级别

IBKR端口配置

平台	演示端口	实盘端口
TWS	4002	7496
Gateway	4002	4001

MCP工具

服务器提供了9个MCP工具：

账户管理

• get_account_summary：获取账户概要信息
• get_positions：获取持仓信息

交易操作

• place_order：下单
• cancel_order：撤单
• get_open_orders：获取未完成订单

市场数据

• get_market_data：获取实时市场数据
• get_historical_data：获取历史数据

连接管理

• connection_status：检查连接状态
• reconnect：重新连接到IBKR

使用示例

下单

{
    "tool": "place_order",
    "arguments": {
        "contract": {
            "symbol": "AAPL",
            "sec_type": "STK",
            "exchange": "SMART",
            "currency": "USD"
        },
        "order": {
            "action": "BUY",
            "total_quantity": 100,
            "order_type": "LMT",
            "lmt_price": 150.0
        }
    }
}

获取持仓

{
    "tool": "get_positions",
    "arguments": {}
}

获取历史数据

{
    "tool": "get_historical_data",
    "arguments": {
        "contract": {
            "symbol": "AAPL",
            "sec_type": "STK",
            "exchange": "SMART",
            "currency": "USD"
        },
        "duration": "1 D",
        "bar_size": "1 min"
    }
}

架构

┌─────────────────────┐
│   MCP客户端         │
│ (Claude桌面版,      │
│ 自定义客户端)       │
└─────────┬───────────┘
          │ HTTP/WebSocket
┌─────────┴───────────┐
│   FastMCP服务器     │
│ (MCP协议层)         │
├─────────────────────┤
│   IBKR MCP服务器    │
│ (业务逻辑)          │
├─────────────────────┤
│   IBKR客户端        │
│ (API封装)           │
└─────────┬───────────┘
          │ TWS API
┌─────────┴───────────┐
│   TWS/Gateway       │
│ (IBKR平台)          │
└─────────────────────┘

开发

项目结构

src/ibkr_mcp_server/
├── __init__.py          # 包初始化
├── server.py            # MCP服务器实现
├── client.py            # IBKR客户端封装
├── models.py            # 数据模型
├── config.py            # 配置管理
├── exceptions.py        # 异常定义
└── cli.py              # 命令行接口

代码标准

• 使用black进行代码格式化
• 使用isort进行导入排序
• 使用flake8进行代码检查
• 使用mypy进行类型检查

测试

# 运行测试
pytest

# 生成覆盖率报告
pytest --cov=src --cov-report=html

部署

Docker部署

# 构建镜像
docker build -t ibkr-mcp-server .

# 运行容器
docker run -p 8080:8080 --env-file .env ibkr-mcp-server

Docker Compose

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

与Claude桌面集成

添加到你的Claude桌面MCP配置中：

{
  "mcpServers": {
    "ibkr": {
      "command": "python",
      "args": ["-m", "ibkr_mcp_server.cli", "serve"],
      "env": {
        "IBKR__HOST": "127.0.0.1",
        "IBKR__PORT": "4002",
        "IBKR__CLIENT_ID": "1"
      }
    }
  }
}

重要注意事项

1. TWS/Gateway：确保IBKR TWS或Gateway正在运行，并且启用了API连接
2. 端口配置：确保TWS/Gateway API端口与您的配置匹配
3. 权限：确保您的账户具有适当的交易权限
4. 风险管理：请在生产环境中实施适当的风险控制措施
5. 市场数据：某些市场数据可能需要订阅

故障排除

常见问题

1. 连接失败：检查TWS/Gateway是否正在运行并且API已启用
2. 客户端ID冲突：使用不同的客户端ID进行多个连接
3. 端口问题：验证您TWS/Gateway设置中的正确端口
4. 市场数据错误：确保您有适当的市场数据订阅

日志记录

启用调试日志以进行故障排除：

LOGGING__LEVEL=DEBUG python -m ibkr_mcp_server.cli serve

许可证

MIT许可证 - 详情请参阅LICENSE文件

贡献

欢迎贡献！请随时提交Pull Request。

支持

如果您遇到任何问题，请提交一个Issue。