AI导哈

IBKR TWS MCP服务器

高性能的模型上下文协议服务器，为Interactive Brokers TWS和IB Gateway提供AI集成层，支持低延迟的交易账户、市场数据和量化扫描仪访问。

  • by AI-Frontier
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 AI-Frontier/ibkr-tws-mcp

使用说明

IBKR TWS MCP服务器📈

高性能、坚固耐用 模型上下文协议（MCP） 服务器提供无缝的AI集成层 盈透证券（IBKR）TWS&IB网关.

该软件包将您的交易账户、头寸、实时市场数据和定量扫描仪直接暴露给LLM（如Claude Desktop），由于其持久的连接架构，延迟极低。

✨ 核心功能

  • ⚡ 持久连接池：采用单个全局活动会话（客户端ID=1），防止TWS速率限制、套接字崩溃和切割工具调用延迟 ~3000ms 归结为 ~50ms.
  • 🧠 代理优化：类型暗示的属性和描述性模式使LLM能够自然地理解市场状态和错误。
  • 🛡️ 线程安全：与FastMCP和同步的并发模型完全兼容 ib_insync 投票。
  • 🧰 综合工具集:
    • 行情 (Market Data)：实时价格快照(live/delayed/historic 级联）和合约搜索(search_contract).
    • 历史 (Historical)：烛台历史数据。
    • 账户 (Account)：PnL摘要、净清算跟踪和控股概述。
    • 资讯 (News)：特定股票和整篇文章查看器的突发新闻标题。
    • 扫描仪 (Scanners)：实时动态市场扫描仪（涨幅最大、最活跃等）。
    • 基本面 (Fundamentals)：获取结构化公司数据(ReportSnapshot, ReportRatios, RESC等等）。
    • 🛡️ 鲁棒性：连接健康检查(check_connection)，手册 reconnect 工具和状态资源(ibkr://status).
  • 🧪 测试就绪：内置 提示 （模板）用于股票分析、投资组合审查和市场扫描，可通过MCP检查器或Claude的提示菜单访问。

🛠 先决条件

  1. Python>=3.12
  2. 盈透证券TWS 或 IB网关 在本地运行。
  3. 在TWS/网关中，导航到 设置>API>设置:
    • 启用 “启用ActiveX和Socket客户端”
    • 检查API端口（默认为 7496 对于TWS Live， 7497 对于TWS Paper， 4001 对于Gateway Live， 4002 Gateway Paper）。

该项目预计港口 4002 默认情况下，它可以被覆盖。

📦 安装和设置

我们建议使用 紫外线 用于快速、可靠的包管理。

# 1. Clone the repository
git clone <your-repo-url>
cd ibkr-tws-mcp

# 2. Setup environment and install dependencies
uv sync

🚀 用法

环境变量

如果这些环境变量与默认值不同，请使用这些环境变量来配置网关：

IBKR_HOST=127.0.0.1
IBKR_PORT=4002

1.通过MCP检查器（Web UI）进行测试

在网络游乐场测试功能：

npx -y @modelcontextprotocol/inspector uv run python -m ibkr_mcp

2.添加到克劳德桌面（或其他MCP客户端）

将此添加到您的 claude_desktop_config.json （通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在Mac上）。

{
  "mcpServers": {
    "ibkr": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/<your-user>/path/to/ibkr-tws-mcp",
        "run",
        "python",
        "-m",
        "ibkr_mcp"
      ],
      "env": {
        "IBKR_HOST": "127.0.0.1",
        "IBKR_PORT": "4002"
      }
    }
  }
}

3.CLI测试与调试

该存储库包括一个独立的客户端CLI，允许您在不启动完整MCP服务器的情况下测试IBKR连接并获取数据。

# General Syntax
uv run ibkr_mcp/client.py --port 4002 <command> [args]

# 1. 💰 Market Price snapshot (Live/Delayed/Historic)
uv run ibkr_mcp/client.py --port 4002 price --symbol AAPL

# 2. 📈 Historical Bars (Last 1 Month daily)
uv run ibkr_mcp/client.py --port 4002 history --symbol TSLA --duration "1 M" --bar-size "1 day"

# 3. 💼 List current account positions
uv run ibkr_mcp/client.py --port 4002 positions

# 4. 🏦 Get account PnL and Net Liquidation status
uv run ibkr_mcp/client.py --port 4002 pnl

# 5. 🗞️ News for currently held positions
uv run ibkr_mcp/client.py --port 4002 positions-news --limit 3

# 6. 📰 News headlines for a specific symbol
uv run ibkr_mcp/client.py --port 4002 news --symbol NVDA --limit 5

# 7. 📖 Fetch full article body (using Code and ID from 'news' results)
uv run ibkr_mcp/client.py --port 4002 article --provider BRFG --id 1234567

# 8. 🔍 Run a Dynamic Market Scanner
uv run ibkr_mcp/client.py --port 4002 scan --code TOP_PERC_GAIN --instrument STK

# 9. 📊 Get Fundamental Company Data (XML)
uv run ibkr_mcp/client.py --port 4002 fundamentals --symbol AAPL --type ReportSnapshot

🛠️ 故障排除与调试

由于TWS设置和网络配置，连接到IBKR可能很棘手。以下是如何调试问题：

1.统一日志记录

服务器和CLI都将详细日志输出到 标准错误.

  • 启用调试日志：设置环境变量 IBKR_LOG_LEVEL=DEBUG.
  • 在克劳德桌面：您可以通过直接检查Claude日志来查看这些日志（通常在 ~/Library/Logs/Claude/mcp.log 在macOS上）。

2.独立CLI测试

在与Claude集成之前，请务必使用内置CLI测试您的连接：

# Test connection and fetch a price with debug logs enabled
IBKR_LOG_LEVEL=DEBUG uv run ibkr_mcp/client.py --port 4002 price --symbol AAPL

3.TWS API设置

如果您收到“拒绝连接”：

  • 确保 TWS/网关 正在运行。
  • 首选 设置>API>设置 在TWS。
  • 验证 “启用ActiveX和Socket客户端” 已检查。
  • 验证您的 港口 匹配您的 IBKR_PORT （Paper默认为4002，Live默认为7496）。
  • 确保 “仅允许来自本地主机的连接” 已检查（或将您的IP添加到受信任的IP）。

4.交互式调试（检查器）

使用MCP检查器查看沙箱中的JSON-RPC流量和测试工具：

npx -y @modelcontextprotocol/inspector uv run python -m ibkr_mcp

5.多客户端冲突

IBKR只允许每个连接一个 Client ID。此服务器使用 client_id=1 默认情况下。如果您有另一个使用ID 1的应用程序（如TradingView桥或自定义脚本），则此服务器将无法连接。

通过以下方式构建 FastMCP 和 取消.

相关 MCP