使用说明

[！注意]

项目状态

该项目目前正在积极开发中。功能可能不完整，可能会发生破坏性更改。

动机

这个项目完全建立在InteractiveBrokersWebneneneba API上，这是一个深思熟虑的设计选择。虽然TWS API功能强大，但Web API为该项目的目标提供了更现代、更灵活的基础。

TWS API MCP与WEB API MCP？

为什么不使用TWS API？ 简单的回答是，WEB API计划更加全面。我所说的更全面的意思是，它将客户管理，特别是报告，带到了同一个地方。另外两个重要原因是：1。Web API是独立的。它不需要您运行TWS桌面软件或IB网关。2.模型上下文协议（MCP）更容易在HTTPS通信而不是TCP/IP套接字之上构建。

如果它更全面，为什么不只使用WEB API？ 三个原因：1。WEB API处于测试版（请参阅局限性2.TWS交易更快、更可靠。3.TWS有一些WEB API没有的交易功能。

虽然其他项目起到了“桥梁”的作用，使TWS API看起来像一个网络API，但它们引入了一个非官方的第三方依赖。该项目通过直接使用官方的IBKR Web API来避免这种风险，确保更好的长期稳定性和支持。

总之：

如果您需要快速可靠的交易，请使用TWS API
如果您需要一个更全面、更适合云的解决方案，请使用WEB API

有关更详细的并排细分，请参阅 TWS与Web API的比较部分。

概述

该项目使用模型上下文协议（MCP）提供交互式代理（IB）API接口。有几种方式可以与盈透证券互动，比如 TWS API，WEB API， Excel RTD FIX等。该项目建立在盈透证券之上网络API.

此开发使用零售身份验证过程，该过程使用客户端门户网关进行管理，客户端门户网关是一个小型Java程序，用于通过适当的身份验证路由本地web请求。

Docker桌面设置

请参阅中的快速演练油管

克隆仓库，设置环境变量并构建镜像

# Clone the repository
git clone https://github.com/rcontesti/IB_MCP.git

# Navigate to the project directory
cd IB_MCP

# Copy the .env.example file to .env and edit as needed
cp .env.example .env

# Build the image
docker compose up --build -d

使用您的IB帐户和凭据进行身份验证：图像启动并运行后，导航到 https://{GATEWAY_BASE_URL}:{GATEWAY_PORT}⁠ （例如： https://localhost:5055/)登录。您还可以在API网关容器的日志中找到登录路径：如果成功，您应该被重定向到一个URL，上面写着：“客户端登录成功”。

将MCP服务器配置文件添加到VS代码中 settings.json.

给定以下环境参数

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

中的VS Code MCP服务器代码段 settings.json 看起来像：

{
  ...
    },
    "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代码中使用MCP服务器（预览版）以供进一步参考。

在Copilot中启动MCP

多容器设置的局限性

用户必须通过与客户端门户网关位于同一台计算机上的浏览器登录才能进行身份验证。
所有API端点调用都必须在对客户端门户网关进行身份验证的同一台计算机上进行。
客户端门户网关不支持使用以/gw/api、/oauth或/oauth2开头的端点。

会话管理

附加的/iserver/auth/ssodh/init端点用于随后重新打开与后端的代理会话，通过该会话可以访问受保护的/iserver端点。

会话将在大约6分钟后超时，而不会发送新的请求或至少每5分钟维护一次/track端点。

为了防止会话超时，应定期调用端点/挠痒痒。建议大约每分钟调用一次此端点。

如果代理会话已超时，但会话仍连接到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端点Staus

TWS与WEB的比较

TWS API（交易者工作站API）： 传统，强大的API。它非常强大、快速、功能丰富，但也更复杂 要求您运行TWS桌面软件或IB网关 在机器上连续工作。
Web API（客户端门户API）： 现代、开发人员友好的RESTful API。它更容易使用，可以在标准HTTPS上工作，并且是独立的（不需要桌面软件）。然而，与TWS API相比，它的性能较差，功能也更少。

对比表

功能	TWS API	Web API（客户端门户API）
技术	TCP/IP套接字，专有二进制协议	RESTful，HTTPS，JSON格式
依赖	要求TWS或IB网关正在运行	独立（不需要TWS/网关）
易用性	陡峭的学习曲线，复杂	更容易，是web开发人员的标准
演出	非常高的速度，低延迟。非常适合高频数据和快速订单执行。	由于HTTPS开销，速度较慢。不适用于HFT
功能	非常全面。访问TWS中的几乎所有功能，包括复杂的订单类型、组合、算法等。	更有限。涵盖核心交易、投资组合和市场数据，但缺乏最先进的功能。
数据流	强大的高频流媒体，用于市场数据、账户更新等。	支持通过WebSocket连接进行流式传输(`/ws`).
历史数据	非常深入和广泛的访问历史数据。	访问良好，但范围和请求频率可能更有限。
认证	直接连接到经过身份验证的TWS/网关会话。	现代基于OAuth的身份验证。web应用程序更安全，但需要更复杂的初始设置。
理想用例	算法交易、自定义交易桌面、高频策略、复杂期权分析。	网络仪表板、移动应用程序、投资组合分析工具、简单的交易机器人、报告。
社区/图书馆	非常成熟。Python、Java、C#、C++等中的许多第三方库。	更新，但不断增长。易于使用任何可以发出HTTP请求的语言。

TWS API：详细的优点和缺点

✅ TWS API优点

无与伦比的功能： 这是它最大的优势。您几乎可以执行TWS桌面平台可以执行的任何操作，包括创建复杂的多分支组合订单（期权策略）、访问数十种算法订单类型（VWAP、TWAP）以及管理财务顾问的分配。
高性能和低延迟： 通过使用直接的套接字连接，TWS API速度极快。它是为速度而构建的，是对延迟敏感的策略的唯一选择。市场数据流是实时和高效的。
广泛的历史数据： 它提供了对历史数据的深度访问，允许直接通过API进行广泛的回溯测试和分析。
成熟与稳健： API已经存在了几十年。它经过了良好的测试，稳定，并且拥有一个庞大的社区，其中有许多编程语言的丰富示例和第三方包装器。

❌ TWS API的缺点

TWS/网关依赖关系： 这是最大的一个缺点。您的应用程序不是独立的。它要求交易者工作站或更轻量级的IB网关的实例在服务器或计算机上全天候运行和登录。这增加了操作复杂性、故障点和资源开销。
陡峭的学习曲线： API并不直观。它使用具有消息ID和特定调用序列的专有请求/响应模型。错误处理可能很棘手，调试需要了解其独特的架构，而不是标准的web协议。
复杂性： 该协议是二进制的，需要一个客户端库（如IB的官方库或第三方包装器）进行交互。您不仅仅发送简单的JSON有效载荷。

Web API（客户端门户API）：详细优点和缺点

✅ 网络优势API

易用性和现代标准： 它是一个标准的RESTful API。如果你曾经使用过网络API，你会觉得宾至如归。您发出HTTPS请求并返回干净、人类可读的JSON。这大大降低了进入门槛。
无桌面依赖关系： 这是它的杀手锏。您的应用程序可以在任何地方运行（例如，云服务器、无服务器功能），而无需维护单独的TWS/Gateway进程。这大大简化了部署和维护。
非常适合网络和移动： 因为它是一个标准的web API，所以非常适合构建基于web的仪表板、移动应用程序或将IBKR数据集成到其他web服务中。
安全身份验证： 它使用OAuth，这是安全、委托访问的行业标准，非常适合用户授予您的应用程序访问其帐户的权限的应用程序。

❌ 网站优点API

功能有限： 它没有展示TWS中可用的全部功能。您可以下标准订单（Market，Limit，Stop），但您找不到TWS API支持的复杂算法或多分支组合订单。
性能较低： HTTPS/JSON的开销使其固有地比TWS API的直接套接字连接慢。它不适合高频或对延迟敏感的交易策略。
速率限制： 作为一项基于网络的服务，它对请求有更明确的速率限制，以确保所有客户端的公平使用。
较新和不太成熟： 虽然现在相当稳定，但它比TWS API更新。您可能偶尔会发现缺少某个功能，或者文档不像几十年前的TWS API那样具有战斗力。

你应该选择哪一个？

如果出现以下情况，则选择TWS API：

你正在构建一个严肃的、自动化的 算法交易系统.
你的策略是 延迟敏感.
你需要放置 复杂订单类型 如期权点差、组合或使用IBKR的内置算法。
您正在构建一个自定义、功能丰富的 桌面交易应用程序.
您对跑步的运营开销感到满意 IB网关24/7.

如果出现以下情况，请选择Web API（客户端门户API）：

您正在构建一个 网络仪表盘 或 移动应用 监控您的投资组合。
你想建立一个 简单交易机器人 执行基本订单（例如，“当AAPL股价达到150美元时，买入100股”）。
您正在构建一个 报告或分析工具.
开发速度和易用性 比原始性能或对每个功能的访问更重要。
你 无法或不想运行专用TWS/Gateway实例.

建筑

该项目由两个主要的Docker服务组成：

api_gateway： 运行Interactive Brokers客户端门户网关以启用对IB REST API的安全访问。包括一个集成的备忘录服务，通过定期调用 /tickle 端点以防止超时。
mcp服务器： FastMCP服务器采用FastAPI构建，提供模型上下文协议接口。包含为位于中的IB API终结点手动开发的路由器 mcp_server/routers/.

📦 盈透证券客户端门户网关Docker容器

这个Docker容器设置并运行 盈透证券（IB）客户门户网关，这是应用程序通过IB REST API连接所必需的。

🔧 这个容器做什么

基本图像：用途 eclipse-temurin:21 （Java 21）与IB网关兼容。
安装依赖项：安装 unzip 用于提取网关档案，以及 curl 对于挠痒服务。
下载网关：从盈透证券官方来源获取最新版本的客户端门户网关并解压缩。
配置:
- 复制自定义 conf.yaml 进入预期的路径(gateway/root/conf.yaml)以配置网关。
- 包括a run_gateway.sh 启动网关并启动集成挠痒器服务的脚本。
- 挠痒器会自动呼叫 /tickle 端点每60秒维护一次会话。
港口暴露：显示端口 5055 （网关使用的默认端口）。根据需要在.env中重写。
启动命令：使用配置文件运行网关和挠痒器服务。

此设置提供了一个自包含的、可复制的环境，用于在容器化环境中安全地运行交互式代理REST API网关和自动会话管理。

📦 IB MCP服务器Docker容器

这个Docker容器设置并运行 盈透证券（IB）模型上下文协议（MCP）服务器，为与IB API网关交互提供了一个接口。

🔧 这个容器做什么

基本图像：用途 ghcr.io/astral-sh/uv:python3.11-bookworm-slim 适用于轻量级Python 3.11环境 uv.
安装依赖项：安装 curl 用于系统依赖关系和用途 uv sync 从以下位置安装Python依赖项 pyproject.toml.
配置:
- 复制 pyproject.toml 以及整个 mcp_server 目录（包括 mcp_server/routers/)放入容器中。
- 集合 PYTHONPATH 到 /app 和 UV_CACHE_DIR 到 /tmp/uv-cache.
- 路由器是手动开发的，位于 mcp_server/routers/ （由于OpenAPI规范验证问题，未自动生成）。
港口暴露：显示由指定的端口 MCP_SERVER_PORT 环境变量（例如。， 5002).
启动命令：使用运行FastAPI服务器 uv run -- python /app/mcp_server/fastapi_server.py.

此设置为具有集成路由器的MCP服务器提供了一个容器化环境，使其能够通过模型上下文协议与IB客户端门户网关通信。

MCP服务器实现模式

此项目使用两种不同的模式来实现MCP服务器：

模式1：旧版mcp.run（）（mcp_server-IB API）

端点: /mcp/ （单层）
备注：使用时 mcp.run()，FastMCP创建了自己的Starlette应用程序，因此 /health 其他FastAPI路由丢失
被...使用: mcp_server （交互式经纪人API包装）

模式2：现代app.mount（）（市场数据、情绪、新闻）

端点: /mcp/mcp/ （由于安装路径+内部路径，因此为双层）
蜜饯: /health 以及所有其他FastAPI路由
实施：用途 mcp_app = mcp.streamable_http_app() + app.mount("/mcp", mcp_app)
推荐新服务

已知问题和依赖关系

FastMCP和Pydantic兼容性

fastmcp==2.10.3 需要 pydantic>=2.11,<2.12
未测试FastMCP兼容性，请勿将pydantic升级到2.11.x以上
看 pyproject.toml 对于固定版本

zsh壳牌注释

使用时 curl URL包含 ?，将URL括在单引号中： curl 'http://localhost:5002/endpoint?param=value'

局限性

克劳德桌面： 目前的开发仅支持可流式传输的HTTP和claude桌面远程MCP服务器支持目前处于测试阶段，可供claude Pro、Max、Team和Enterprise计划的用户使用（截至2026年2月）。
克莱恩： Cline在远程服务器的流式HTTP方面仍然存在问题。

参考文献

贡献

我们欢迎对这个项目的贡献！如果你想做出贡献，请遵循以下准则：

分叉存储库 并从以下位置创建分支 main.
报告错误 通过以清晰的描述和重现步骤打开一个问题。
建议功能 通过打开一个问题来讨论你的想法。
提交拉取请求 用于错误修复、新功能或改进。请确保您的代码遵循现有风格，包含相关测试，并有明确的提交消息。

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

使用说明

项目状态

动机

TWS API MCP与WEB API MCP？

目录

概述

Docker桌面设置

多容器设置的局限性

会话管理

未来工作

端点状态

TWS与WEB的比较

对比表

TWS API：详细的优点和缺点

✅ TWS API优点

❌ TWS API的缺点

Web API（客户端门户API）：详细优点和缺点

✅ 网络优势API

❌ 网站优点API

你应该选择哪一个？

建筑

📦 盈透证券客户端门户网关Docker容器

🔧 这个容器做什么

📦 IB MCP服务器Docker容器

🔧 这个容器做什么

MCP服务器实现模式

模式1：旧版mcp.run（）（mcp_server-IB API）

模式2：现代app.mount（）（市场数据、情绪、新闻）

已知问题和依赖关系

FastMCP和Pydantic兼容性

zsh壳牌注释

局限性

参考文献

贡献

许可证

相关 MCP

PineScript策略管理工具

Obsidian笔记搜索服务

n8n工作流管理服务

Web漏洞扫描MCP服务器

知识库AI代理服务器

Neo N3 区块链 MCP 服务器