IBKR MCP Docker
中文文档 |英语
一个模型上下文协议（MCP）服务器，通过Docker提供盈透证券（IBKR）交易功能。
______________________________________________________________________
⚠️ 重要免责声明
本软件仅用于信息和教育目的。使用本软件即表示您承认并同意：
- 你全权负责 用于通过此软件进行的所有交易决策和操作
- 您使用此软件 风险自负。作者和贡献者不对任何经济损失、损害或责任负责
- 此软件连接到您的 真实金融账户使用不当可能导致重大经济损失
- 总是 测试与 票据交易 在与真实账户一起使用之前，请先使用模式
- 在使用之前，您应该充分了解自动交易和盈透证券平台的风险
使用风险自负。没有任何形式的保证。
______________________________________________________________________
这个项目是做什么的？
该项目提供了 桥 在模型上下文协议（MCP）和盈透证券交易平台之间。它允许AI助手和应用程序：
- 查询实时市场数据 -获取实时股票价格、历史数据和期权链
- 监控帐户状态 -检查余额、头寸和投资组合绩效
- 执行交易 -以编程方式下达市价单、限价单和止损单
- 与AI工作流程集成 -使用自然语言与您的经纪账户进行交互
特性
此MCP服务器提供以下功能：
账户管理
- 查询账户现金流量和余额
- 查看账户摘要和净清算价值
职位管理
- 查询当前职位
- 查看未实现和已实现损益
订单管理
- 查询订单状态（未结订单和已完成订单）
- 下达限价订单
- 下达市场订单
- 下达止损订单
市场数据
- 获取实时股票价格 *（需要订阅市场数据）*
- 查询历史库存数据
- 访问选项链 *（需要订阅市场数据）*
建筑
该项目整合了两项服务：
- IB网关 -用途 提供盈透证券网关
主要特点：
- FastMCP集成：使用基于装饰器的工具注册来生成干净的Python代码
- Pydantic模型：所有响应均使用Pydantic模型进行结构化、验证数据的键入
- 类型安全：完整的类型提示和从函数签名自动生成模式
- HTTP/SSE传输：通过HTTP在以下位置公开MCP服务器
http://127.0.0.1:8080/mcp - 只读模式：可选的只读模式，用于禁用订单下达、修改和取消
这两个服务都是通过单个 .env 为了简单起见，请使用文件。
先决条件
- Docker和Docker Compose
- 盈透证券账户（纸盘交易或实时交易）
- IBKR帐户凭据
- 市场数据订阅 （实时价格数据和期权数据所需）
备注：某些功能需要主动订阅IBKR市场数据。如果没有订阅，您可能会收到某些市场的延迟数据或没有数据。
快速入门（推荐：使用预构建图像）
我们建议使用预构建的Docker镜像 更容易设置和自动更新。预构建的图像包括：
- ✅ 经过测试和验证
- ✅ 多平台（amd64/arm64）
- ✅ 根据版本自动构建
- ✅ 无需本地构建
使用预构建图像
- 创建
.env示例中的文件：
cp .env.example .env- 编辑
.env使用您的IBKR凭据进行归档（请参阅 配置 下节）
- 启动服务：
docker-compose up -d替代方案：从源代码构建
如果您更喜欢从源代码构建：
- 克隆此存储库：
git clone https://github.com/metaif/ibkr-mcp-docker.git
cd ibkr-mcp-docker- 创建
.env示例中的文件：
cp .env.example .env- 编辑
.env提交您的IBKR凭据：
# IBKR Gateway Configuration
IBKR_USERID=your_username
IBKR_PASSWORD=your_password
IBKR_TRADING_MODE=paper # or 'live' for live trading
IBKR_GATEWAY_PORT=4002
# MCP Server Configuration
SERVER_PORT=8080 # MCP server will be available at http://127.0.0.1:8080/mcp
# Read-Only Mode (optional)
READONLY=false # Set to 'true' to disable order operations
# Optional: VNC password for monitoring the gateway
VNC_PASSWORD=your_vnc_password- 更新
docker-compose.yml从源代码构建：
用构建配置替换图像行：
services:
mcp-server:
build: .
# Remove or comment out: image: ghcr.io/metaif/ibkr-mcp-docker:latest- 构建并启动服务：
docker-compose up -d --build配置
环境变量
所有配置都是通过 .env 文件。以下是对每个参数的详细解释：
IBKR网关配置
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
IBKR_TRADING_MODE | 交易方式： paper 对于纸质交易， live 用于实时交易 | paper | 是的 |
IBKR_USERID | IBKR实时交易用户名 | - | 是（实时） |
IBKR_PASSWORD | IBKR实时交易密码 | - | 是（实时） |
IBKR_USERID_PAPER | IBKR纸质交易用户名 | - | 是（纸质） |
IBKR_PASSWORD_PAPER | IBKR纸质交易密码 | - | 是（纸质） |
IBKR_GATEWAY_LIVE_PORT | IB网关端口用于实时交易 | 4003 | 没有 |
IBKR_GATEWAY_PAPER_PORT | 用于票据交易的IB网关端口 | 4004 | 没有 |
VNC_PASSWORD | 用于监视网关UI的VNC密码 | - | 否 |
MCP服务器配置
| 变量 | 描述 | 默认值 | 必填 |
|---|---|---|---|
SERVER_PORT | MCP服务器HTTP端口。服务器将位于 `http://127.0.0.1: | ||
| /mcp` | 8080 | 没有 | |
READONLY | 只读模式。设置为 true/1/yes 禁用订单操作 | false | 没有 |
配置示例
编辑您的 .env 文件：
# For Paper Trading
IBKR_TRADING_MODE=paper
IBKR_USERID_PAPER=your_paper_username
IBKR_PASSWORD_PAPER=your_paper_password
IBKR_GATEWAY_PAPER_PORT=4004
# For Live Trading - BE CAREFUL!
# IBKR_TRADING_MODE=live
# IBKR_USERID=your_live_username
# IBKR_PASSWORD=your_live_password
# IBKR_GATEWAY_LIVE_PORT=4003
# MCP Server
SERVER_PORT=8080
# Safety: Enable read-only mode to prevent accidental trades
READONLY=true
# Optional: VNC for monitoring
VNC_PASSWORD=12345678用法
启动服务
启动IB网关和MCP服务器：
docker-compose up -d这将：
- 启动IB网关容器并连接到IBKR
- 启动MCP服务器容器
- 在以下位置公开MCP服务器
http://127.0.0.1:8080/mcp
使用MCP服务器
MCP服务器可通过HTTP/SSE访问：
# Access the MCP endpoint
curl http://localhost:8080/mcp该端点与基于HTTP的MCP客户端兼容，可以集成到您的应用程序中。
监控
您可以在端口5900上使用VNC监视IB网关：
# Using a VNC client, connect to:
localhost:5900查看日志：
# All services
docker-compose logs -f
# Just the MCP server
docker-compose logs -f mcp-server
# Just the IB Gateway
docker-compose logs -f ib-gateway可用的MCP API工具
MCP服务器公开了以下工具。每个工具都使用Pydantic模型返回键入的、经过验证的响应。
帐户和投资组合API
这些API不需要市场数据订阅：
get_account_summary→AccountSummary
- 获取账户余额和现金流信息 - 退货： net_liquidation, cash_balance, total_cash_value, buying_power, gross_position_value - 无需订阅市场数据
get_positions→List[Position]
- 获取所有当前职位 - 每个职位包括： symbol, quantity, avg_cost, market_price, unrealized_pnl, realized_pnl - 无需订阅市场数据
get_orders→List[OrderInfo]
- 获取所有订单（已打开和已完成） - 包括： order_id, symbol, action, order_type, status, filled, avg_fill_price - 无需订阅市场数据
市场数据API
这些API需要订阅市场数据：
get_stock_price→StockPrice
- 获取实时股票价格 - 参数： symbol （必填）， exchange （可选，默认：“SMART”） - 退货： bid, ask, last, close, volume, timestamp - ⚠️ 需要订阅市场数据 - 备注：如果没有订阅，可能会返回延迟的数据或在某些市场失败
get_historical_data→List[HistoricalBar]
- 获取历史库存数据 - 参数： symbol （必填）， duration （默认值：“1D”）， bar_size （默认值：“1小时”）， exchange （可选） - 返回：每个条的OHLCV数据(date, open, high, low, close, volume) - 根据所请求的数据，可能需要订阅市场数据
get_option_chain→List[OptionChain]
- 获取股票的期权链 - 参数： symbol （必填）， exchange （可选） - 退货：可用 strikes, expirations, multipliers - ⚠️ 期权需要市场数据订阅
交易API
这些API不需要订阅市场数据，但可以修改您的帐户：
place_limit_order→OrderResult
- 下达限价订单 - 参数： symbol, action （买入/卖出）， quantity, limit_price, exchange （可选） - ⚠️ 启用READONLY模式时禁用 - ⚠️ 小心：这是真正的订单！
place_market_order→OrderResult
- 下达市价订单 - 参数： symbol, action （买入/卖出）， quantity, exchange （可选） - ⚠️ 启用READONLY模式时禁用 - ⚠️ 小心：这是真正的订单！
place_stop_order→OrderResult
- 下达止损单 - 参数： symbol, action （买入/卖出）， quantity, stop_price, exchange （可选） - ⚠️ 启用READONLY模式时禁用 - ⚠️ 小心：这是真正的订单！
cancel_order→CancelResult
- 取消现有订单 - 参数： order_id （必填） - ⚠️ 启用READONLY模式时禁用
所有工具使用 Pydantic模型 用于类型安全、经过验证的响应，具有清晰的字段描述。
只读模式
启用只读模式以防止下单、修改和取消：
READONLY=true启用时：
- ✅ 所有查询操作（头寸、订单、价格等）正常工作
- ❌ 下单工具(
place_limit_order,place_market_order,place_stop_order,cancel_order)将返回拒绝状态 - 👍 可用于无交易风险的监控和分析
停止服务
docker-compose down要同时删除卷，请执行以下操作：
docker-compose down -v配置参考
完整的环境变量参考
请参阅 配置 以上部分为详细的参数说明。
| 变量 | 类型 | 默认值 | 描述 |
|---|---|---|---|
IBKR_TRADING_MODE | 字符串 | paper | paper 或 live |
IBKR_USERID | string | - | 实时交易用户名 |
IBKR_PASSWORD | string | - | 实时交易密码 |
IBKR_USERID_PAPER | string | - | 纸质交易用户名 |
IBKR_PASSWORD_PAPER | string | - | 纸质交易密码 |
IBKR_GATEWAY_LIVE_PORT | 整数 | 4003 | 实时交易端口 |
IBKR_GATEWAY_PAPER_PORT | 整数 | 4004 | 纸张贸易港 |
SERVER_PORT | 整数 | 8080 | MCP服务器端口 |
READONLY | 布尔值 | false | 启用只读模式 |
VNC_PASSWORD | string | - | VNC密码 |
故障排除
连接问题
如果MCP服务器无法连接到IB网关：
- 检查两个容器是否都在运行：
docker-compose ps- 验证IB网关是否接受连接：
docker-compose logs ib-gateway- 确保您的IBKR凭据在
.env文件
身份验证问题
如果您的IBKR帐户启用了2FA：
- 网关将等待2FA完成
- 监控VNC连接以完成2FA
- 这
TWOFA_TIMEOUT_ACTION=restart如果2FA超时，设置将重新启动网关
纸上交易vs现场交易
- 票据交易 (
IBKR_TRADING_MODE=paper)：使用端口4004，连接到IBKR纸币交易
- ✅ 测试安全 - 不涉及真钱
- 实时交易 (
IBKR_TRADING_MODE=live)：使用端口4003，连接到实时IBKR帐户
- ⚠️ 危险：真钱有风险！ - 所有订单都会影响您的真实账户
⚠️ 警告：切换到实时交易模式时要格外小心！始终先在纸上交易中进行彻底测试。
市场数据订阅
某些API需要从盈透证券订阅市场数据：
所需订阅
- 实时股票报价：需要订阅相关交易所（纽约证券交易所、纳斯达克等）
- 选项数据：需要OPRA（期权价格报告机构）订阅
- 延迟的数据：根据市场情况，可能免费提供，延迟15-20分钟
如何检查订阅
- 登录您的IBKR帐户https://www.interactivebrokers.com
- 首选 账户管理 → 设置 → 市场数据订阅
- 查看您的活动订阅并添加任何需要的订阅
无订阅
如果没有订阅，可能会出现以下情况：
get_stock_price：对于某些市场，可能会返回延迟数据（延迟15-20分钟）或错误get_option_chain：可能会失败或不返回任何数据get_historical_data：可能适用于某些数据范围，但实时条形图将失败
许可证
麻省理工学院
参考文献
- 快速MCP -用于构建MCP服务器的现代Python框架
- ib_async文档
- 派丹蒂克 -使用Python类型提示进行数据验证
- 模型上下文协议
- 互动经纪人API