IBKR-Portmanteau

<h1 align="center">IBKR 合成词</h1> <img width="4128" height="1024" alt="Gemini_Generated_Image_7r3gwh7r3gwh7r3g" src="https://github.com/user-attachments/assets/bc6d3baf-4d32-43af-8cda-c6e4f78f62c0" /> [](https://www.gnu.org/licenses/agpl-3.0) [](COMMERCIAL-LICENSE.md) [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](https://github.com/sponsors/Almoon-D) [](https://buymeacoffee.com/almoon.d) **IBKR 合成词** 是一款基于 **模型上下文协议（MCP）** 标准构建的统一金融服务器。该服务器严格设计为 **只读** 网关，为您的大型语言模型（在 Cursor、Claude Desktop、ChatGPT、Gemini 或 VS Code 中）提供一个安全的通道，以实时探索、分析和提取您的投资组合和全球市场的先进指标，并在此基础上进行推理，内置宏观和期权分析。 > **为什么不直接使用官方 Interactive Brokers MCP？** Interactive Brokers 自己的工具对于原始账户访问和订单执行非常出色。合成词是一个不同的、互补的东西：一个 **只读分析大脑**，它将您的 IBKR 数据与免费的市场和宏观数据源（Yahoo、Binance、CoinGecko、FRED、世界银行、ECB/Frankfurter、SEC EDGAR）融合，计算 Black-Scholes-Merton Greeks、隐含波动率和投资组合压力测试，并将所有内容合并为您的账户基础货币（EUR-friendly）。没有订单执行表面意味着没有资本执行风险。 ## 🌐 任意部署（本地和云端准备） 在您的机器上运行以进行快速分析，或在私人 VPS 上托管以实现 24/7 始终在线的 AI 数据桥。核心保持轻量级、稳定，并与任何单个桌面隔离。 ### 架构亮点和原生桥梁 * **Interactive Brokers（客户端门户 API）**：通过直接平台数据管道实现实时余额、综合头寸扫描和期权链匹配。 * **直接异步网络栈**：通过 `httpx` 直接与原始 Yahoo Finance、Binance、CoinGecko、FRED、世界银行、ECB/Frankfurter 和 SEC EDGAR 端点通信，具有重试/回退和多源回退。 * **主动驱逐内存缓存**：具有后台驱逐的锁隔离内存缓存 - 没有数据库文件写锁，没有长期内存泄漏。 * **向量化数学引擎**：NumPy 矩阵 Black-Scholes-Merton 期权定价，带有嵌入的 Newton-Raphson 隐含波动率求解器。 --- ## 🛠️ 系统需求 * **Python 3.11、3.12、3.13** （完全向后兼容）。 * **Python 3.14** （优化的异步事件循环执行）。 所有运行时依赖项都已在 `requirements.txt` 中固定（并在 `pyproject.toml` 中镜像）。 --- ## 💻 本地安装和设置指南（PC） ### 1. 克隆仓库并准备环境 ```bash git clone https://github.com/Almoon-D/IBKR-Portmanteau.git cd IBKR-Portmanteau # 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # 在 Windows 上使用：venv\Scripts\activate # 安装固定的依赖项 pip install -r requirements.txt ``` ### 2. 设置 IBKR 客户端门户网关 该服务器需要本地 HTTP 访问官方 Interactive Brokers 网关，**在启动 MCP 服务器之前运行并认证**。 1. **下载**：从官方 [IBKR 客户端门户 API 文档](https://interactivebrokers.github.io/cpwebapi/) 下载客户端门户网关。 2. **解压**：在仓库外解压。 3. **配置（可选）**：编辑 `root/conf/conf.yaml`；它默认在 `https://localhost:5000` 上运行。 4. **运行**：Linux/macOS `bin/run.sh conf/conf.yaml` · Windows `bin/run.bat conf/conf.yaml`。 5. **认证**：打开 `https://localhost:5000`，使用您的 IBKR 凭证登录并批准 2FA。一旦会话显示已认证，MCP 服务器将在启动时自动连接。 ### 3. 环境变量（支持 `.env`） 复制 `.env.example` 到 `.env`（自动加载），或 `export` 变量： ```bash # FRED 支持宏观引擎和实时无风险利率。在以下网址获取免费密钥： # https://fredaccount.stlouisfed.org/apikeys export FRED_API_KEY="your_api_key_here" # 仅当您的 IBKR 网关在自定义主机/接口上运行时： export IBKR_GATEWAY_URL="https://localhost:5000/v1/api" # 可选：网关的 CA 证书路径（否则禁用 localhost 的 TLS 验证）。 export IBKR_CACERT="" # 作为描述性 User-Agent，SEC EDGAR 需要用于 get_fundamentals： export SEC_CONTACT_EMAIL="you@example.com" ``` ### 4. 运行 MCP 服务器 ```bash python server.py --transport stdio ``` ### 5. AI 客户端集成（Claude Desktop / Cursor） #### 对于 Claude Desktop - 添加到 `claude_desktop_config.json`： ```json { "mcpServers": { "ibkr_portmanteau": { "command": "python", "args": ["C:/path/to/IBKR-Portmanteau/server.py", "--transport", "stdio"], "env": { "FRED_API_KEY": "your_api_key_here", "IBKR_GATEWAY_URL": "https://localhost:5000/v1/api", "SEC_CONTACT_EMAIL": "you@example.com" } } } } ``` #### 对于 Cursor / VS Code（MCP 扩展） 1. 设置 → **模型** → **MCP** → **+ 添加新 MCP 服务器**。 2. 名称 `ibkr_portmanteau`，类型 `command`。 3. 命令：`python /absolute/path/to/IBKR-Portmanteau/server.py --transport stdio` --- ## ☁️ 云部署指南（Oracle Cloud / VPS） 由于服务器是 **只读** 的，它适合云拓扑（无资本执行风险）。但是，由于 Interactive Brokers 的激进反机器人周界（Cloudflare/Akamai），**不要在数据中心 IP 上直接运行 Java 客户端门户网关** - 网络登录会被 CAPTCHA 阻止。使用安全网格代替。 ### 通过 Tailscale（VPN 网格）推荐的网络架构 ``` [您的远程笔记本电脑/工作区] ↓ （私有，加密 WireGuard 网格隧道） [Tailscale 网络] ↓ [您的云 VPS 实例（MCP 服务器）] ──→ [Yahoo/Binance/CoinGecko/FRED/世界银行/ECB/SEC] ↓ （内部网格流量安全路由回家） [您的家庭 PC（活动客户端门户网关桥）] ``` ### 部署步骤（Ubuntu 计算实例） 1. **安装 Tailscale** 在您的家庭机器（网关）和云实例上 - 一个安全的对等覆盖网络，无需原始防火墙端口。 2. **通过您的家庭节点的 Tailscale IP 路由网关 API**： ```bash export IBKR_GATEWAY_URL="https://100.X.X.X:5000/v1/api" # 您的家庭机器的 Tailscale IP ``` 3. **部署**：克隆仓库，`pip install -r requirements.txt`，启动。使用 `--transport sse` 如果暴露给外部 API 网关，或保持 `stdio` 如果 LLM 客户端在同一台机器上运行。 --- ## 📊 暴露的 MCP 工具 服务器将这些分析能力注册到您的 LLM 的上下文中： 1. `search_instrument` — 免费文本资产发现，以解析未知符号。 2. `get_market_snapshot` — 实时报价（Bid/Ask/Last），IBKR → Yahoo（无密钥图表）→ Binance/CoinGecko 回退，具有自动全局票据处理。 3. `get_historical_ohlcv` — 历史 OHLCV 条形与窗口（`interval`、`period`、`limit`），无密钥 Yahoo 图表，具有重试。 4. `get_fx_rate` — 实时外汇，**ECB/Frankfurter 主要** （EUR-native）与 Yahoo 回退。 5. `get_options_chain_with_greeks` — 期权流动性链与向量化 **Delta、Gamma、Vega、Theta** 和 Newton-Raphson 隐含波动率。 6. `get_portfolio_summary` — 综合多币种净清算价值、头寸权重、**聚合美元希腊字母** 和 **压力测试场景（-10%，-20%）**，具有期权凸性和 IV 倾斜调整。 7. `get_global_macro_scanner` — FRED（美国）+ 世界银行（全球）宏观系列，按语义别名或原始代码。 8. `get_fundamentals` — **SEC EDGAR** 公司基本面（收入、净收入、总资产、稀释后每股收益、股份）用于美国上市股票。 9. `query_ibkr_endpoint` — 受保护的只读直通到原始 IBKR 客户端门户 REST API。 10. `search_fred_series` — 通过关键词发现 FRED 经济系列标识符。 两个参考资源也暴露：`manuals://exploration_manual` 和 `manuals://api_reference`。 --- <img width="2816" height="1536" alt="Gemini_Generated_Image_t4sk66t4sk66t4sk" src="https://github.com/user-attachments/assets/3e10f8f9-4531-4b5f-9a92-b79c96c4445b" /> --- ## ⚠️ 免责声明 本软件仅用于信息和教育目的。 它 **不是** 投资、财务、法律或税务建议，使用它不会与您的经纪人建立代理或信托关系。 市场数据来源于第三方，可能会延迟、不准确或不完整 - **请始终与您的经纪人核实** 后再采取行动。 该软件 **不提供任何形式的担保**；请参阅 [`DISCLAIMER.md`](DISCLAIMER.md) 和 [`LICENSE`](LICENSE)。 --- ## ☕ 捐款和支持 如果此服务器帮助您优化投资组合、评估尾部风险或将 Interactive Brokers 数据链接到自定义 AI 工具，请考虑通过 GitHub Sponsors 或 Buy Me a Coffee 支持持续维护。 [](https://github.com/sponsors/Almoon-D) [](https://buymeacoffee.com/almoon.d) --- ## 星级历史 <a href="https://www.star-history.com/?repos=Almoon-D%2FIBKR-Portmanteau&type=date&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Almoon-D/IBKR-Portmanteau&type=date&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Almoon-D/IBKR-Portmanteau&type=date&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=Almoon-D/IBKR-Portmanteau&type=date&legend=top-left" /> </picture> </a> --- ## 📄 许可证 **IBKR 合成词** 采用双重许可： * **开源** 遵循 **GNU Affero 通用公共许可证 v3.0（AGPLv3）** - 参见 [`LICENSE`](LICENSE)。 AGPLv3 的网络条款（§13）要求任何提供修改版本为网络服务的人也必须向其用户提供相应的源代码。 * **商业许可证** - 在不具有 AGPLv3 共同开发义务的情况下，将软件用于封闭源代码产品或托管/SaaS 产品。 参见 [`COMMERCIAL-LICENSE.md`](COMMERCIAL-LICENSE.md)。 第三方数据源受其自身条款的约束；参见 [`DATA_SOURCES.md`](DATA_SOURCES.md)。 版权（C）2026 AlmoonD。保留所有权利。