使用说明

IBKR MCP Docker

中文文档 |英语

一个模型上下文协议（MCP）服务器，通过Docker提供盈透证券（IBKR）交易功能。

⚠️ 重要免责声明

本软件仅用于信息和教育目的。使用本软件即表示您承认并同意：

你全权负责 用于通过此软件进行的所有交易决策和操作
您使用此软件 风险自负。作者和贡献者不对任何经济损失、损害或责任负责
此软件连接到您的 真实金融账户使用不当可能导致重大经济损失
总是测试与 票据交易 在与真实账户一起使用之前，请先使用模式
在使用之前，您应该充分了解自动交易和盈透证券平台的风险

使用风险自负。没有任何形式的保证。

这个项目是做什么的？

该项目提供了桥在模型上下文协议（MCP）和盈透证券交易平台之间。它允许AI助手和应用程序：

查询实时市场数据 -获取实时股票价格、历史数据和期权链
监控帐户状态 -检查余额、头寸和投资组合绩效
执行交易 -以编程方式下达市价单、限价单和止损单
与AI工作流程集成 -使用自然语言与您的经纪账户进行交互

特性

此MCP服务器提供以下功能：

账户管理

查询账户现金流量和余额
查看账户摘要和净清算价值

职位管理

查询当前职位
查看未实现和已实现损益

订单管理

查询订单状态（未结订单和已完成订单）
下达限价订单
下达市场订单
下达止损订单

市场数据

获取实时股票价格 （需要订阅市场数据）
查询历史库存数据
访问选项链 （需要订阅市场数据）

建筑

该项目整合了两项服务：

IB网关 -用途 ib网关docker 提供盈透证券网关
MCP 服务器 -基于Python的MCP服务器快速MCP 和 ib_async

主要特点：

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:<PORT>/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网关Docker
ib_async文档
派丹蒂克 -使用Python类型提示进行数据验证
模型上下文协议
互动经纪人API