IBKR Portfolio Builder

ibkr-portfolio-builder-mcp

面向 使用 Interactive Brokers 自上而下构建投资组合 的远程 MCP 服务。可用作 Claude.ai 自定义连接器、Claude Code MCP，或任何 HTTP MCP 客户端。

大多数 ibkr-mcp 服务只提供单项查询基础工具，如 get_quote、get_position、place_order。本服务提供的是研究工作流：一个包含 468 个筛选器、覆盖 16 个类别且按策略意图（价值／成长／收益／动量／质量／事件／……）标记的类型化目录、每项扫描适用的金融工具、反向配对链接，以及实时新闻和账户访问能力——因此，大模型可以真正自上而下地构建投资组合（选择行业／策略 → 运行扫描 → 与新闻交叉参考 → 筛选候选项），而不是自下而上地盲目寻找股票代码。

为什么要开发它

我开发这个项目，是因为社区中现有的 IBKR-MCP 服务都把 IBKR 当作“查询单只股票代码”的数据源。这与大多数零售券商 UI 的使用方式相符，但并非有效构建投资组合的实际方式。

良好的自上而下工作流如下：

1. 宏观论点（“利率即将下降，派息股票应该会重新估值”）→
2. 策略意图（“给我看看针对美国大盘股、偏重质量的收益筛选条件”）→
3. 筛选器组合（运行股息收益率 + ROE + 低负债筛选；取交集）→
4. 事件／新闻背景（“这些股票中，有没有未来两周内公布财报的？有没有负面的分析师评级调整？”）→
5. 缩小候选范围（“五个股票代码，按我的标准排序，可进行更深入的尽职调查”）。

要用大模型实现这一点，MCP 服务需要提供研究词汇体系，而不只是原始 API。这正是本服务要填补的空白：

• 类型化扫描目录——包含 16 个类别中 468 个 IBKR 扫描代码（Fundamentals、Price Movement、Dividends、Options & Volatility、Events & Earnings、52/26/13 Week High-Low、ESG、Bonds、……），并自动标记 28 个策略意图标签（value、growth、quality、income、momentum_up、momentum_down、analyst、technical、gap、volatility、events、leverage、efficiency、risk_adjusted、……）。大模型询问“美国股票有哪些价值类扫描？”时，就会得到清晰且可筛选的结果，而不必试图从训练数据中猜测扫描代码。
• 反向配对链接——预先计算每组 HIGH_X ↔ LOW_X 和 X_ASC ↔ X_DESC 配对，因此大模型可以切换方向（“LOW_PE_RATIO 的反向条件是什么？”），无需猜测。
• 逐项扫描的金融工具映射——目录会标明每项扫描适用于哪些金融工具，如 STK、ETF、OPT、BOND 等。这样，大模型就不会再把 Refinitiv 扫描发送给债券工具并得到空结果。
• 筛选器目录——单独的类型化数值筛选器映射表（priceAbove、peRatioBelow、divYieldAbove、growthRateAbove、avgVolumeAbove、marketCapAbove、……），按类别分组，并附有各类金融工具的适用性说明。
• 新闻与筛选器集成在同一工具界面——使用同一连接器、同一身份验证和同一对话。大模型可以将扫描结果与近期头条或即将公布的财报进行交叉筛选，无需切换上下文。
• 两种身份验证模式——面向 Claude.ai 自定义连接器的完整 OAuth 2.1（DCR + PKCE + well-knowns），以及适用于其他所有场景的静态 bearer token。使用同一服务和同一组工具。

这仍是一个早期服务。IBKR API 对模拟账户实际可查看的内容有不少限制（尤其是历史新闻权限）。但目录和工作流结构已达到生产就绪状态，而且它们是大模型驱动研究循环的关键基础。

快速信息

• 传输方式： /mcp 上的 Streamable HTTP。
• 身份验证： OAuth 2.1（PKCE + RFC 7591 动态客户端注册）和/或静态 bearer token。可通过 AUTH_MODE 选择。
• 持久化： 目前仅使用内存（容器重启后会重置会话 / DCR 客户端 / OAuth 令牌）。Redis 已列入路线图，见下文。
• IBKR 连接： ib-gateway（ghcr.io/gnzsnz/ib-gateway:stable）作为同一 compose 中的同级服务运行；默认使用只读 API 模式下的模拟账户。
• 构建基础： FastMCP + ib_async。

工具

与 IBKR 官方 MCP 的 9 个只读工具功能对等（跳过两个写入 / 下单指令工具，详见路线图），另有 5 个筛选器 / 新闻 / 目录工具，这些正是此服务的存在意义。

工具	功能
ib_account_summary	查询已连接的模拟或实盘账户的 NetLiquidation / BuyingPower / TotalCashValue / AvailableFunds / UnrealizedPnL。
ib_positions	查询受管理账户中的未平仓头寸，包括数量 / 平均成本 / 按市值计价 / 未实现盈亏。
ib_open_orders	查询当前有效订单及其状态、已成交 / 剩余数量、平均成交价格。
ib_trades	查询近期已执行的成交（days_back 时间范围，IBKR 将历史记录限制在约 7 天内）。
ib_price_snapshot	查询美国股票当前的买价 / 卖价 / 最新价 / 最高价 / 最低价 / 成交量。清晰显示 IBKR 的市场数据限制消息。
ib_price_history	查询任意时长 / K 线周期的 OHLCV 数据（1 day、1 hour、5 mins……）。无论是否订阅市场数据，始终可用。
ib_search_contracts	按名称 / 部分股票代码模糊搜索 IBKR 合约数据库。
ib_contract_details	完整合约元数据 — long_name、industry、category、subcategory、交易时段、有效交易所。为结合行业自上而下筛选提供支持。
ib_scan_catalog	类型化扫描目录。可按 category、strategy、instrument、自由文本 query 筛选；也可通过 list_meta=true 返回所有可用类别 + 策略的完整列表。
ib_filter_catalog	按类别（price、volume、market_cap、fundamentals、technical、options）分组的筛选参数代码，并附带适用的工具说明。
ib_screener_codes	对原始 scan-parameters.xml 代码进行子串搜索（旧版 / 后备工具）。适用于查找尚未纳入精选目录的较新供应商代码。
ib_screener	运行 IBKR 扫描 — 传入 scan_code、instrument、location 以及可选的价格 / 成交量筛选条件。返回排名 + 股票代码 + 交易所。
ib_news_providers	列出已订阅的 IBKR 新闻提供商（Briefing.com、Dow Jones 等）。
ib_news_for_symbol	跨所有已订阅提供商获取美国股票的新闻标题。仅返回标题；如果账户没有历史新闻权限，会清晰显示 notice 字段。
ib_news_article	根据 provider_code + article_id 获取单篇文章正文。⚠️ 可能会产生单篇文章费用（尤其是 Dow Jones）。

关于下单的说明。 IBKR 官方 MCP 还提供 Create Order Instruction 和 Delete Order Instruction。本服务有意不提供这两项工具 — 它以 READ_ONLY_API=yes 模式运行 ib-gateway，因此即使工具调用路由错误，也无法下单。订单执行应由另一个拥有独立审批关卡的服务负责。路线图中还提到一种可能的“仅暂存”指令工具：它只会写入本地存储，不会触及 IBKR。

身份验证

AUTH_MODE 用于选择服务器接受的身份验证机制。默认值为 both。

模式	接受的方式	必需的环境变量
oauth	仅接受由 OAuth 签发的令牌。Claude.ai 自定义连接器必须使用此模式。	LOGIN_PASSWORD
bearer	仅接受静态 Authorization: Bearer <token>。跳过 OAuth 流程——最适合 CLI 客户端、Claude Code 和你自己的脚本。	STATIC_BEARER_TOKEN
both (默认)	接受 OAuth 令牌或静态 bearer 令牌。	LOGIN_PASSWORD 或 STATIC_BEARER_TOKEN 至少需要一个。

OAuth 端点（/authorize、/token、/register、/.well-known/*、/login）始终会注册。在 bearer 模式下，它们不会生效——无需在你的 README 中指向这些端点。

生成密钥

uv run --no-project python -c "import secrets; print(secrets.token_urlsafe(48))"   # bearer token
uv run --no-project python -c "import secrets; print(secrets.token_urlsafe(48))"   # session secret

使用静态 bearer 令牌

curl -X POST https://YOUR.DOMAIN/mcp \
  -H "Authorization: Bearer $STATIC_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

从 Claude.ai 连接（OAuth）

设置 → 连接器 → 添加自定义连接器 → URL：https://YOUR.DOMAIN/mcp → 将 OAuth 客户端 ID/密钥留空（Claude.ai 使用 DCR）。Claude.ai 开始 OAuth 流程时，系统会提示你输入 LOGIN_PASSWORD。

运行

cp .env.example .env
# edit .env: set TWS_USERID / TWS_PASSWORD (paper account), LOGIN_PASSWORD, STATIC_BEARER_TOKEN, PUBLIC_BASE_URL
docker compose up -d

默认情况下，此操作会从 GitHub Container Registry 拉取已发布的多架构镜像：ghcr.io/adwiteeymauriya/ibkr-portfolio-builder-mcp:latest。若要改为在本地构建（例如迭代开发源代码时），请先运行 docker compose build ibkr-mcp。

首次启动后，ib-gateway 需要约 60–90 秒才能完成 IBKR 登录。使用 docker logs -f ibkr-mcp-gateway 查看日志。

仅供本地使用时（bearer 令牌客户端，不使用 Claude.ai），这样就足够了——现在 http://localhost:8000/mcp 已可提供服务。Claude.ai 自定义连接器需要可公开访问的 HTTPS URL，因此必须在前面配置带 TLS 的反向代理。

为 Claude.ai 配置 TLS

任选一种。两种方式最终都会提供可用的 https://your-host/mcp 和有效证书。

选项 1 — Cloudflare Tunnel（无需公网 IP，无需端口转发）。 适合服务器运行在家庭网络中或位于 NAT 后的虚拟机上。Cloudflare 免费提供主机名和 TLS；隧道守护进程会从服务器向外连接到 Cloudflare 边缘节点。

# One-time: install cloudflared, then
cloudflared tunnel login
cloudflared tunnel create ibkr-mcp
cloudflared tunnel route dns ibkr-mcp ibkr-mcp.your-domain.com

~/.cloudflared/config.yml：

tunnel: ibkr-mcp
credentials-file: /home/you/.cloudflared/<TUNNEL_ID>.json
ingress:
  - hostname: ibkr-mcp.your-domain.com
    service: http://localhost:8000
  - service: http_status:404

使用 cloudflared tunnel run ibkr-mcp 运行（或通过 cloudflared service install 安装为 systemd 单元）。然后在 .env 中设置 PUBLIC_BASE_URL=https://ibkr-mcp.your-domain.com，并运行 docker compose restart ibkr-mcp。

选项 2 — 使用 Let's Encrypt 的 Caddy 反向代理。 适合拥有公网 IP 且开放了 80/443 端口的服务器。Caddy 会自动获取证书。

Caddyfile：

ibkr-mcp.your-domain.com {
    reverse_proxy localhost:8000
}

使用 caddy run 运行（或安装为系统服务：运行 sudo caddy start 并添加 systemd 单元）。.env 中的修改与上文相同。

两种方式都要求 PUBLIC_BASE_URL 与你提供给 Claude.ai 的 URL 完全一致——Claude.ai 会据此验证 OAuth 发行方。

LLM 提示词示例（自上而下的工作流）

1. Discovery:
   "List the strategies and categories available in ib_scan_catalog."

2. Strategy intent:
   "Find me value scans for US stocks. Show me their inverse codes too."

3. Composition:
   "Run LOW_PE_RATIO on STK.US.MAJOR with priceAbove $20 and avgVolumeAbove
    1,000,000, top 30. Cross-reference with HIGH_RETURN_ON_EQUITY top 30.
    Show me overlap."

4. Event context:
   "For the overlap list, check ib_news_for_symbol for any negative
    headlines in the last 7 days, and Events & Earnings scans for
    upcoming earnings within 14 days."

5. Narrow:
   "Rank the survivors by liquidity and tell me which two you'd dig
    into next."

路线图

领域	项目
身份验证	基于 Redis 的会话、DCR 客户端、OAuth 令牌
身份验证	每个令牌的作用域（read-only、read-news、screener-only，……）
交易品种	期权（链、希腊值、IV/价格计算）
交易品种	期货（ContFuture、通过 Bag 组合）
交易品种	债券（搜索 + 报价）
交易品种	外汇 + 加密货币
交易所	非美国股票路由（欧盟、香港、日本、澳大利亚）
交易所	支持货币的 ib_account_summary
研究	Reuters 基本面数据（reqFundamentalDataAsync）
研究	实时流式 K 线 + 逐笔行情
研究	Level 2 订单簿
研究	每日 PnL 流（pnlAsync、pnlSingleAsync）
研究	顾问子账户（reqFamilyCodesAsync）
研究	将目录导入 Memgraph，以支持多跳查询
研究	扩展 ib_news_search
风险	ib_what_if_order（保证金预览，不执行订单）
风险	本地暂存指令工具（不写入 IBKR）

欢迎就以上任何项目提交问题或 PR。

目录结构

.
├── Dockerfile
├── docker-compose.yml             # connector + ib-gateway, internal IBKR network
├── pyproject.toml                 # uv-managed: fastmcp, itsdangerous, uvicorn, ib_async
├── uv.lock
├── .env.example
├── LICENSE                        # MIT
├── scan-parameters.xml            # IBKR's authoritative scan params (raw XML)
├── scanner_reference.json         # IBKR-categorized scanner reference
├── scanner_params.json            # Flat dump of scan codes + filters
├── scripts/
│   └── build_catalog.py           # Regenerates src/connector/data/* from the three source files above
└── src/
    └── connector/
        ├── settings.py            # env-driven config (incl. AUTH_MODE)
        ├── auth.py                # LoginGatedOAuthProvider + static bearer override + /login
        ├── ibkr.py                # ib_async connection helper (connect-per-call)
        ├── screener.py            # raw scan-parameters.xml substring search (fallback tool)
        ├── catalog.py             # typed scan + filter catalog loaders + filtering
        ├── tools.py               # 15 MCP tools wired into FastMCP
        ├── server.py              # FastMCP + Starlette wiring + uvicorn entry
        └── data/
            ├── scan_catalog.json  # generated
            └── filter_catalog.json # generated

许可证

MIT。

致谢

• 感谢 gnzsnz/ib-gateway-docker 提供无头 ib-gateway 镜像。
• 感谢 ib_async 提供异步 IBKR 客户端。
• 感谢 FastMCP 提供内置 OAuth 支持的 MCP 服务框架。

免责声明

本软件会连接到你的 Interactive Brokers 账户。默认情况下，它会以只读 API 模式连接模拟账户运行——即使工具尝试下单，也无法下单。如果你切换到真实账户，风险由你自行承担。工具输出均不构成投资建议；策略标签只是词汇辅助工具，并非推荐引擎。