IBKR-Portmanteau

<h1 align="center">IBKR Portmanteau</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 Portmanteau** is a unified financial server built on the **Model Context Protocol (MCP)** standard. Designed strictly as a **Read-Only** gateway, it gives your Large Language Models (in Cursor, Claude Desktop, ChatGPT, Gemini or VS Code) a secure channel to explore, analyse and extract advanced metrics from your portfolio and global markets in real time — and then *reason* over them with built-in macro and options analytics. > **Why not just use the official Interactive Brokers MCP?** IBKR's own tooling is excellent for raw account access and order execution. Portmanteau is a different, complementary thing: a **read-only analytics brain** that fuses your IBKR data with free market and macro sources (Yahoo, Binance, CoinGecko, FRED, World Bank, ECB/Frankfurter, SEC EDGAR), computes Black-Scholes-Merton Greeks, implied volatility and portfolio stress tests, and consolidates everything into your account's base currency (EUR-friendly). No order-execution surface means no capital-execution risk. ## 🌐 Deploy Anywhere (Local & Cloud Ready) Run it on your own machine for quick analysis, or host it on a private VPS for a 24/7 always-on AI data bridge. The core stays lightweight, stable, and decoupled from any single desktop. ### Architectural Highlights & Native Bridges * **Interactive Brokers (Client Portal API)**: real-time balances, consolidated position sweeps, and option-chain matching via direct platform data pipelines. * **Direct Async Network Stack**: communicates directly with the raw Yahoo Finance, Binance, CoinGecko, FRED, World Bank, ECB/Frankfurter and SEC EDGAR endpoints via `httpx`, with retry/backoff and multi-source fallbacks. * **Active-Evict Memory Cache**: a lock-isolated in-memory cache with background eviction — no database file write-locking, no long-tail memory leaks. * **Vectorized Math Engine**: NumPy matrix Black-Scholes-Merton option pricing with an embedded Newton-Raphson implied-volatility solver. --- ## 🛠️ System Requirements * **Python 3.11, 3.12, 3.13** (full backward compatibility). * **Python 3.14** (optimised async event-loop execution). All runtime dependencies are pinned in `requirements.txt` (and mirrored in `pyproject.toml`). --- ## 💻 Local Installation & Setup Guide (PC) ### 1. Clone the Repository & Prepare the Environment ```bash git clone https://github.com/Almoon-D/IBKR-Portmanteau.git cd IBKR-Portmanteau # Create and activate the virtual environment python -m venv venv source venv/bin/activate # On Windows use: venv\Scripts\activate # Install pinned dependencies pip install -r requirements.txt ``` ### 2. Set Up the IBKR Client Portal Gateway This server needs local HTTP access to the official Interactive Brokers gateway, **running and authenticated before you start the MCP server**. 1. **Download**: from the official [IBKR Client Portal API docs](https://interactivebrokers.github.io/cpwebapi/), download the *Client Portal Gateway*. 2. **Extract**: unzip outside this repository. 3. **Configure** (optional): edit `root/conf/conf.yaml`; it serves on `https://localhost:5000` by default. 4. **Run**: Linux/macOS `bin/run.sh conf/conf.yaml` · Windows `bin/run.bat conf/conf.yaml`. 5. **Authenticate**: open `https://localhost:5000`, log in with your IBKR credentials and approve 2FA. Once the session shows authenticated, the MCP server hooks in automatically on startup. ### 3. Environment Variables (`.env` supported) Copy `.env.example` to `.env` (auto-loaded), or `export` the variables: ```bash # FRED powers the macro engine and the live risk-free rate. Get a free key at: # https://fredaccount.stlouisfed.org/apikeys export FRED_API_KEY="your_api_key_here" # Only if your IBKR gateway runs on a custom host/interface: export IBKR_GATEWAY_URL="https://localhost:5000/v1/api" # Optional: path to a CA cert for the gateway (otherwise TLS verify is disabled for localhost). export IBKR_CACERT="" # Used as the descriptive User-Agent SEC EDGAR requires for get_fundamentals: export SEC_CONTACT_EMAIL="you@example.com" ``` ### 4. Running the MCP Server ```bash python server.py --transport stdio ``` ### 5. AI Client Integration (Claude Desktop / Cursor) #### For Claude Desktop — add to `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" } } } } ``` #### For Cursor / VS Code (MCP extensions) 1. Settings → **Models** → **MCP** → **+ Add New MCP Server**. 2. Name `ibkr_portmanteau`, Type `command`. 3. Command: `python /absolute/path/to/IBKR-Portmanteau/server.py --transport stdio` --- ## ☁️ Cloud Deployment Guide (Oracle Cloud / VPS) Because the server is **Read-Only**, it suits cloud topologies (no capital-execution risk). However, due to Interactive Brokers' aggressive anti-bot perimeter (Cloudflare/Akamai), **do not run the Java Client Portal Gateway directly on a data-center IP** — web logins get CAPTCHA-blocked. Use a secure mesh instead. ### Recommended Network Architecture via Tailscale (VPN Mesh) ``` [Your Remote Laptop / Workspace] ↓ (Private, encrypted WireGuard mesh tunnel) [Tailscale Network] ↓ [Your Cloud VPS Instance (MCP Server)] ──→ [Yahoo/Binance/CoinGecko/FRED/World Bank/ECB/SEC] ↓ (Internal mesh traffic routed securely home) [Your Home PC (Active Client Portal Gateway Bridge)] ``` ### Deployment Steps (Ubuntu Compute Instance) 1. **Install Tailscale** on both your home machine (gateway) and the cloud instance — a secure peer-to-peer overlay, no raw firewall ports. 2. **Route the Gateway API** through your home node's Tailscale IP: ```bash export IBKR_GATEWAY_URL="https://100.X.X.X:5000/v1/api" # Your home machine's Tailscale IP ``` 3. **Deploy**: clone the repo, `pip install -r requirements.txt`, launch. Use `--transport sse` if exposing to an external API gateway, or keep `stdio` if the LLM client runs on the same machine. --- ## 📊 Exposed MCP Tools The server registers these analytical capabilities into your LLM's context: 1. `search_instrument` — free-text asset discovery to resolve unknown symbols. 2. `get_market_snapshot` — real-time quote (Bid/Ask/Last), IBKR → Yahoo (keyless chart) → Binance/CoinGecko fallback, with automatic global-ticker handling. 3. `get_historical_ohlcv` — historical OHLCV bars with windowing (`interval`, `period`, `limit`), keyless Yahoo chart with retry. 4. `get_fx_rate` — spot FX, **ECB/Frankfurter primary** (EUR-native) with Yahoo fallback. 5. `get_options_chain_with_greeks` — options liquidity chain with vectorized **Delta, Gamma, Vega, Theta** and Newton-Raphson implied volatilities. 6. `get_portfolio_summary` — consolidated multi-currency Net Liquidation Value, position weights, **aggregate Dollar-Greeks**, and **stress-test scenarios (−10%, −20%)** with options-convexity and IV-skew adjustments. 7. `get_global_macro_scanner` — FRED (US) + World Bank (global) macro series by semantic alias or raw code. 8. `get_fundamentals` — **SEC EDGAR** company fundamentals (revenue, net income, total assets, diluted EPS, shares) for US-listed tickers. 9. `query_ibkr_endpoint` — guarded read-only passthrough to the raw IBKR Client Portal REST API. 10. `search_fred_series` — discover FRED economic-series identifiers by keyword. Two reference resources are also exposed: `manuals://exploration_manual` and `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 This software is provided for informational and educational purposes only. It is **not** investment, financial, legal or tax advice, and using it does not create a broker, adviser or fiduciary relationship. Market data is sourced from third parties and may be delayed, inaccurate or incomplete — **always verify against your broker** before acting. The software is provided **without warranty of any kind**; see [`DISCLAIMER.md`](DISCLAIMER.md) and [`LICENSE`](LICENSE). --- ## ☕ Donations & Support If this server helps you optimise your portfolio, evaluate tail risks, or link Interactive Brokers data to custom AI tooling, consider supporting continued maintenance via GitHub Sponsors or Buy Me a Coffee. [](https://github.com/sponsors/Almoon-D) [](https://buymeacoffee.com/almoon.d) --- ## Star History <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> --- ## 📄 License **IBKR Portmanteau** is dual-licensed: * **Open source** under the **GNU Affero General Public License v3.0 (AGPLv3)** — see [`LICENSE`](LICENSE). AGPLv3's network clause (§13) requires that anyone offering a modified version as a network service also make the corresponding source available to its users. * **Commercial license** — for using the software in a closed-source product or a hosted/SaaS offering **without** the AGPLv3 copyleft obligations. See [`COMMERCIAL-LICENSE.md`](COMMERCIAL-LICENSE.md). Third-party data sources are subject to their own terms; see [`DATA_SOURCES.md`](DATA_SOURCES.md). Copyright (C) 2026 AlmoonD. All rights reserved.