ib_mcp

🚀 交互式经纪商API项目

本项目基于交互式经纪商（Interactive Brokers）的Web API构建，借助模型上下文协议（MCP）提供API接口，在交易系统开发中，为用户提供了更现代、灵活的解决方案，满足不同场景下的交易需求。

🚀 快速开始

环境准备

本项目使用Docker进行部署，你可以参考 YOUTUBE 上的快速演示。

操作步骤

1. 克隆仓库、设置环境变量并构建镜像

# 克隆项目仓库
git clone https://github.com/rcontesti/IB_MCP.git

# 进入项目目录
cd IB_MCP

# 复制.env.example文件为.env并按需编辑
cp .env.example .env

# 构建镜像
docker compose up --build -d

2. 使用IB账户和凭证进行认证 镜像启动并运行后，访问 https://{GATEWAY_BASE_URL}:{GATEWAY_PORT}（例如：https://localhost:5055/）进行登录。你也可以在API网关容器的日志中找到登录路径，如图所示： 如果登录成功，你将被重定向到显示 “Client login succeeds” 的URL。
3. 将MCP服务器配置文件添加到VS Code的 settings.json 中 假设环境参数如下：

MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=5002
MCP_SERVER_PATH=/mcp
MCP_TRANSPORT_PROTOCOL=streamable-http

VS Code的 settings.json 中的MCP服务器代码片段如下：

{
  ...
        },
        "chat.mcp.discovery.enabled": true,
        "mcp": {
            "inputs": [],
            "servers": {
                "time": {
                "command": "docker",
                "args": ["run", "-i", "--rm", "mcp/time"]
                },
                "ib-web": {
                    "type": "http",
                    "url": "http://localhost:5002/mcp/",
                }
            }
        },
        "workbench.colorTheme": "Tomorrow Night Blue"
}

或者，你可以在项目根目录下创建一个 .vscode/mcp.json 文件，内容如下：

{
    "servers": {
        "ib-mcp-server": {
            "type": "http",
            "url": "http://localhost:5002/mcp/"
        }
    },
    "inputs": []
}

更多参考信息请查看 在VS Code中使用MCP服务器（预览版）。 4. 在Copilot中启动MCP

✨ 主要特性

• 基于官方Web API：直接使用交互式经纪商的官方Web API，避免引入第三方依赖，确保长期稳定性和支持。
• 多容器架构：采用Docker容器化技术，包含API网关、会话管理服务、路由生成器和MCP服务器等组件，便于部署和管理。
• 支持MCP协议：通过模型上下文协议（MCP）与API网关交互，提供更灵活的接口。

📦 安装指南

克隆项目

git clone https://github.com/rcontesti/IB_MCP.git
cd IB_MCP

配置环境变量

复制 .env.example 文件为 .env，并根据需要编辑其中的环境变量。

cp .env.example .env

构建并启动容器

docker compose up --build -d

登录认证

访问 https://{GATEWAY_BASE_URL}:{GATEWAY_PORT} 进行登录认证。

VS Code配置

将MCP服务器配置添加到VS Code的 settings.json 或 .vscode/mcp.json 中。

💻 使用示例

基础用法

在VS Code中配置MCP服务器后，你可以在Copilot中启动MCP并与交互式经纪商的API进行交互。

高级用法

根据不同的业务需求，你可以通过修改MCP服务器的配置文件，实现更复杂的功能，如自定义路由、处理不同类型的请求等。

📚 详细文档

多容器设置的限制

• 用户必须在与客户端门户网关相同的机器上通过浏览器登录才能进行认证。
• 所有API端点调用必须在客户端门户网关进行认证的同一台机器上进行。
• 以 /gw/api、/oauth 或 /oauth2 开头的端点均不支持在客户端门户网关中使用。

会话管理

使用 /iserver/auth/ssodh/init 端点重新打开经纪会话，以访问受保护的 /iserver 端点。 会话在大约6分钟内未发送新请求或至少每5分钟维护一次 /tickle 端点时将超时。为防止会话超时，建议大约每分钟调用一次 /tickle 端点。 如果经纪会话已超时，但会话仍连接到IBKR后端，/auth/status 的响应将返回 'connected': true 和 'authenticated': false。调用 /iserver/auth/ssodh/init 端点将初始化一个新的经纪会话。

未来工作

• 自动生成端点：由于当前 IB REST API (2.16.0) OpenAPI规范 验证失败，自动路由生成功能目前无法正常工作。你可以在以下链接进行验证：
  • https://oas-validation.com/
  • https://editor.swagger.io/ 目前该规范有351个错误，因此路由端点目前是手动构建的，并在完成后更新其状态。由于官方OpenAPI规范存在问题以及IB团队目前的重点，目前无法实现自动路由生成，路由正在手动构建。
• 添加OAuth

端点状态

端点目前是手动构建的，完整的 API端点状态列表 请查看链接。

TWS与Web API对比

TWS API（Trader Workstation API）

• 优点：功能强大、速度快、功能丰富，具有极高的性能和低延迟，提供广泛的历史数据访问，成熟且稳定，有大量的第三方库支持。
• 缺点：需要在机器上持续运行TWS桌面软件或IB网关，学习曲线陡峭，协议复杂。

Web API（Client Portal API）

• 优点：易于使用，基于标准的HTTPS协议，独立运行，无需桌面软件，适合Web和移动应用开发，采用现代的OAuth认证方式。
• 缺点：功能有限，性能较低，存在请求速率限制，相对较新且成熟度不如TWS API。

选择建议

• 选择TWS API：如果你正在构建严肃的自动化算法交易系统、对延迟敏感、需要使用复杂的订单类型、构建自定义的桌面交易应用程序，并且愿意承担运行IB网关的运营开销。
• 选择Web API：如果你正在构建Web仪表板、移动应用程序、简单的交易机器人、报告或分析工具，更注重开发速度和易用性，而不是原始性能或访问所有功能，或者无法或不想运行专用的TWS/Gateway实例。

对比表格

| 特性 | TWS API | Web API（Client Portal API） | | ---- | ---- | ---- | | 技术 | TCP/IP套接字，专有二进制协议 | RESTful，HTTPS，JSON格式 | | 依赖 | 需要运行TWS或IB网关 | 独立运行（无需TWS/Gateway） | | 易用性 | 学习曲线陡峭，复杂 | 易于使用，适合Web开发者 | | 性能 | 速度极快，低延迟，适合高频数据和快速订单执行 | 由于HTTPS开销较慢，不适合高频交易 | | 功能 | 极其全面，几乎可以访问TWS的所有功能 | 功能有限，覆盖核心交易、投资组合和市场数据 | | 数据流式传输 | 强大的高频市场数据流 | 通过WebSocket连接（/ws）支持流式传输 | | 历史数据 | 非常深入和广泛的历史数据访问 | 访问良好，但范围和请求频率可能更有限 | | 认证 | 直接连接到经过认证的TWS/Gateway会话 | 基于现代OAuth的认证，更适合Web应用 | | 理想用例 | 算法交易、自定义交易桌面、高频策略、复杂期权分析 | Web仪表板、移动应用、投资组合分析工具、简单交易机器人、报告 | | 社区/库 | 非常成熟，有许多第三方库 | 较新但在增长，易于与任何可以进行HTTP请求的语言一起使用 |

架构

项目由4个主要组件组成：

• api_gateway：在Docker容器中运行交互式经纪商的客户端门户网关，以实现对IB REST API的安全访问。
• ticker_service：负责通过定期调用 /tickle 端点来维护交互式经纪商会话，防止会话超时。该服务在Docker容器中运行。
• routers_generator：根据官方文档自动创建FastAPI路由，并将其保存到 routers 目录中。
• mcp_server：使用FastMCP构建的MCP服务器，通过添加先前生成的路由与API网关进行交互。该服务也在Docker容器中运行。

交互式经纪商客户端门户网关Docker容器

此Docker容器设置并运行交互式经纪商（IB）客户端门户网关，这是应用程序通过IB REST API进行连接所必需的。

容器功能

• 基础镜像：使用 eclipse-temurin:21（Java 21）以与IB网关兼容。
• 安装依赖：安装 unzip 用于提取网关存档。
• 下载网关：从交互式经纪商的官方源获取最新版本的客户端门户网关并解压。
• 配置：
  • 将自定义的 conf.yaml 复制到预期路径（gateway/root/conf.yaml）以配置网关。
  • 添加自定义的 run_gateway.sh 脚本作为容器入口点。
• 端口暴露：暴露端口 5055（网关使用的默认端口），可在 .env 中根据需要覆盖。
• 启动命令：使用配置文件运行网关。

交互式经纪商路由生成器Docker容器 [进行中]

由于官方Open Api Json文件验证失败，路由目前是手动开发的。详情请参阅 未来工作 和 端点状态。

IB MCP服务器Docker容器

此Docker容器设置并运行交互式经纪商（IB）模型上下文协议（MCP）服务器，为与IB API网关进行交互提供接口。

容器功能

• 基础镜像：使用 ghcr.io/astral-sh/uv:python3.11-bookworm-slim 提供轻量级的Python 3.11环境。
• 安装依赖：安装 curl 作为系统依赖，并使用 uv sync 从 pyproject.toml 安装Python依赖。
• 配置：将 pyproject.toml 和整个 mcp_server 目录复制到容器中，设置 PYTHONPATH 为 /app，UV_CACHE_DIR 为 /tmp/uv-cache。
• 端口暴露：暴露由 MCP_SERVER_PORT 环境变量指定的端口（例如 5002）。
• 启动命令：使用 uv run -- python /app/mcp_server/fastapi_server.py 运行FastAPI服务器。

🔧 技术细节

项目架构

项目采用多容器架构，通过Docker容器化技术将各个组件隔离运行，提高了系统的可维护性和可扩展性。

容器技术

使用Docker容器化技术，确保各个组件的环境一致性和独立性。

协议和接口

基于RESTful API和MCP协议，与交互式经纪商的API进行交互。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

参考资料

• IB WEB API参考
• IB WEB API openapi文档 （已过时！）
• IB WEB API参考页面
• FAST MCP
• FAST MCP文档
• FAST MCP openapi集成
• ibeam
• fastapi-codegen
• openapi spec验证器仓库
• openapi spec验证器文档

贡献指南

我们欢迎对本项目的贡献！如果您想贡献代码，请遵循以下指南：

1. Fork仓库 并从 main 分支创建您的分支。
2. 报告问题：通过创建一个清晰描述问题和重现步骤的issue来报告问题。
3. 建议功能：通过创建一个issue来讨论您的想法。
4. 提交拉取请求：提交修复问题、添加新功能或改进的拉取请求。请确保您的代码符合现有风格，包含相关测试，并具有清晰的提交消息。