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實例。

對比表格

架構

項目由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. 提交拉取請求：提交修復問題、添加新功能或改進的拉取請求。請確保您的代碼符合現有風格，包含相關測試，並具有清晰的提交消息。