{"id":49418363,"url":"https://github.com/groupthink-dev/ib-blade-mcp","last_synced_at":"2026-04-29T04:12:33.454Z","repository":{"id":353470673,"uuid":"1205991538","full_name":"Groupthink-dev/ib-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-24T02:10:34.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T04:16:37.907Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T13:22:34.000Z","updated_at":"2026-04-24T02:10:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/ib-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/ib-blade-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/ib-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fib-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fib-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fib-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fib-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/ib-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fib-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:12:26.304Z","updated_at":"2026-04-29T04:12:33.439Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IB Blade MCP\n\nInteractive Brokers MCP server for Claude, Sidereal, and any MCP-compatible client. Portfolio monitoring, market data, order management, and market scanners — all through the IB Client Portal Gateway.\n\nBuilt for the [Model Context Protocol](https://modelcontextprotocol.io).\n\n## Why another IB MCP?\n\n| | **ib-blade-mcp** | rcontesti/IB_MCP | code-rabi/interactive-brokers-mcp | Hellek1/ib-mcp |\n|---|---|---|---|---|\n| **Approach** | CP Gateway REST | CP Gateway REST | Bundled Gateway + JRE | TWS socket (ib_async) |\n| **Headless** | Yes (gateway runs separately) | Yes | Bundles JRE + Gateway in npm | Requires running TWS/Gateway |\n| **Order safety** | Triple gate: env var + confirm param + what-if preview | Basic | Basic confirm | Read-only by design |\n| **Token efficiency** | Pipe-delimited, compact formatters, batch endpoints | JSON dumps | JSON dumps | JSON dumps |\n| **Credential handling** | Gateway handles auth; MCP never sees IB passwords. Scrubbing on errors | Env var passwords | OAuth or env var passwords | Env var passwords |\n| **Rate limiting** | Concurrency semaphore + snapshot throttle | None | None | None |\n| **HTTP transport** | stdio + streamable-http with bearer auth | stdio only | stdio only | stdio only |\n| **Security posture** | No bundled JRE, no IB credentials in MCP process, bearer auth for remote | Passwords in env | Ships a JRE | Passwords in env |\n| **IB Australia** | Works with any IB entity (AU, US, UK, etc.) | Global only | Global only | Global only |\n| **Tests** | pytest + mypy + ruff CI | Minimal | Minimal | Good (pytest) |\n\n### Key design decisions\n\n1. **Gateway separation.** This MCP server connects to an already-authenticated Client Portal Gateway. Your IB credentials never touch the MCP process. The gateway handles authentication, session management, and market data subscriptions.\n\n2. **Triple order safety.** Three independent gates prevent accidental trades:\n   - `IB_WRITE_ENABLED=true` environment variable (off by default)\n   - `confirm=true` parameter on every order tool (off by default)\n   - `ib_order_preview` returns margin impact and commission before you commit\n\n3. **Token efficiency.** Every tool returns compact pipe-delimited output, not raw JSON. Positions, orders, and trades each fit in a few hundred tokens instead of thousands.\n\n4. **No bundled infrastructure.** Unlike alternatives that bundle JRE and gateway binaries inside npm packages, this server is a lightweight Python process that talks to your existing gateway.\n\n## What this covers\n\n- **21 tools** across 6 categories\n- Portfolio: accounts, positions, summary, cash balances, P\u0026L\n- Market data: contract search, quotes, batch snapshots, historical bars\n- Orders: list, status, preview, place, modify, cancel, confirm\n- Scanners: parameter discovery, scanner execution\n- Trades: recent executions\n\n## Quick start\n\n### Prerequisites\n\n1. **IB Client Portal Gateway** — download from [IB API page](https://www.interactivebrokers.com/en/trading/ib-api.php) and run it:\n   ```bash\n   cd clientportal-gw \u0026\u0026 bin/run.sh root/conf.yaml\n   ```\n2. Authenticate by opening `https://localhost:5000` in a browser\n3. Python 3.12+\n\n### Install\n\n```bash\n# From PyPI (when published)\nuv pip install ib-blade-mcp\n\n# From source\ngit clone https://github.com/groupthink-dev/ib-blade-mcp\ncd ib-blade-mcp \u0026\u0026 uv sync\n```\n\n### Configure\n\n```bash\n# Required\nexport IB_GATEWAY_URL=\"https://localhost:5000\"\n\n# Optional\nexport IB_ACCOUNT_ID=\"U1234567\"       # Auto-detected if omitted\nexport IB_SSL_VERIFY=\"false\"           # For self-signed gateway certs\nexport IB_WRITE_ENABLED=\"false\"        # Enable order placement\nexport IB_MCP_API_TOKEN=\"\"             # Bearer token for HTTP transport\n```\n\n### Run\n\n```bash\n# stdio transport (default — for Claude Code, Sidereal, etc.)\nib-blade-mcp\n\n# HTTP transport (for remote/tunnel access)\nIB_MCP_TRANSPORT=http IB_MCP_PORT=8790 ib-blade-mcp\n```\n\n### Claude Code configuration\n\nAdd to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ib\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/ib-blade-mcp\", \"ib-blade-mcp\"],\n      \"env\": {\n        \"IB_GATEWAY_URL\": \"https://localhost:5000\",\n        \"IB_SSL_VERIFY\": \"false\",\n        \"IB_WRITE_ENABLED\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\n### System (2)\n\n| Tool | Description |\n|------|-------------|\n| `ib_status` | Session status, auth state, write gate, rate limits |\n| `ib_tickle` | Keep gateway session alive (heartbeat) |\n\n### Portfolio (5)\n\n| Tool | Description |\n|------|-------------|\n| `ib_accounts` | List linked brokerage accounts |\n| `ib_positions` | Open positions with P\u0026L, market value, cost basis |\n| `ib_portfolio_summary` | NAV, cash, unrealised P\u0026L, buying power, margin |\n| `ib_cash_balances` | Cash balances by currency |\n| `ib_pnl` | Daily and unrealised P\u0026L |\n\n### Market Data (6)\n\n| Tool | Description |\n|------|-------------|\n| `ib_contract_search` | Find contracts by symbol or name → conid |\n| `ib_contract_detail` | Contract info: exchange, currency, multiplier |\n| `ib_quote` | Live snapshot: last, bid, ask, volume, change |\n| `ib_historical` | Historical OHLCV bars |\n| `ib_scanner_params` | Available scanner types and filters |\n| `ib_scanner_run` | Run market scanner (gainers, most active, etc.) |\n\n### Order Query (3)\n\n| Tool | Description |\n|------|-------------|\n| `ib_orders` | Live/recent orders with fill status |\n| `ib_order_status` | Detailed status of a specific order |\n| `ib_trades` | Recent trade executions |\n\n### Order Write (5) — gated\n\n| Tool | Gate | Description |\n|------|------|-------------|\n| `ib_order_preview` | write | What-if preview: margin, commission, equity impact |\n| `ib_place_order` | write + confirm | Place order (LMT, MKT, STP, STP_LMT, MIDPRICE) |\n| `ib_confirm_order` | write | Reply to gateway confirmation prompts |\n| `ib_modify_order` | write + confirm | Modify quantity, price, or TIF |\n| `ib_cancel_order` | write | Cancel an open order |\n\n## Output format\n\nAll tools return compact pipe-delimited text optimised for LLM token efficiency:\n\n```\nconid | symbol | pos | mkt_value | avg_cost | unrealised_pnl | pnl%\n265598 | AAPL | 100 | $17.5K | 150.00 | $2500.00 | +16.7%\n9579970 | BHP.ASX | 500 | $22.5K | 42.00 | $1500.00 | +7.1%\n```\n\nMoney values use compact formatting: `$1.2M`, `$45.3K`, `$500.00`.\n\n## Security model\n\n- **Gateway isolation.** IB credentials are managed by the Client Portal Gateway, not this MCP server. The MCP process never sees your IB username or password.\n- **Write gating.** All order operations require `IB_WRITE_ENABLED=true`. Order placement additionally requires `confirm=true` per call.\n- **Credential scrubbing.** Session tokens, cookies, and auth headers are stripped from error messages before returning to the LLM.\n- **Bearer auth.** HTTP transport optionally requires `Authorization: Bearer \u003ctoken\u003e` with timing-safe comparison.\n- **No bundled binaries.** Unlike some alternatives, this server doesn't ship JRE, gateway, or other large dependencies.\n\n## IB Australia\n\nThis server works with any Interactive Brokers entity. IB Australia (ABN 98 166 929 568, AFSL 453554) accounts use the same Client Portal Gateway as any other region. The account ID determines jurisdiction — no code-level configuration needed.\n\nAUD base currency is handled natively in formatters.\n\n## Architecture\n\n```\n┌──────────────┐     stdio/HTTP      ┌──────────────┐    REST/JSON    ┌──────────────┐\n│  MCP Client  │ ◄──────────────────► │ ib-blade-mcp │ ◄────────────► │  IB Gateway   │\n│ (Claude, etc)│                      │  (FastMCP)   │                │ (CP Gateway)  │\n└──────────────┘                      └──────────────┘                └──────┬───────┘\n                                                                             │\n                                                                    IB Auth + Market Data\n                                                                             │\n                                                                      ┌──────▼───────┐\n                                                                      │   IB Servers  │\n                                                                      └──────────────┘\n```\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `IB_GATEWAY_URL` | Yes | — | Client Portal Gateway URL |\n| `IB_ACCOUNT_ID` | No | auto-detect | Default account ID |\n| `IB_SSL_VERIFY` | No | `true` | Verify SSL certs (set `false` for self-signed) |\n| `IB_WRITE_ENABLED` | No | `false` | Enable order operations |\n| `IB_MCP_TRANSPORT` | No | `stdio` | Transport: `stdio` or `http` |\n| `IB_MCP_HOST` | No | `127.0.0.1` | HTTP bind address |\n| `IB_MCP_PORT` | No | `8790` | HTTP port |\n| `IB_MCP_API_TOKEN` | No | — | Bearer token for HTTP transport |\n\n## Development\n\n```bash\nmake install-dev    # Install with dev + test deps\nmake test           # Run unit tests\nmake test-cov       # Run with coverage\nmake check          # Lint + format + typecheck\nmake run            # Start the server\n```\n\n## Roadmap\n\n- [ ] **WebSocket order streaming** — subscribe to order status changes via gateway WebSocket for real-time fill notifications\n- [ ] **OAuth 2.0 Web API** — direct IB Web API access with `private_key_jwt`, eliminating the gateway dependency\n- [ ] **Flex Queries** — historical trade reports and statements via IB Flex Query system\n- [ ] **Watchlist management** — create and manage watchlists through the gateway\n- [ ] **Sidereal marketplace** — publish as a certified Sidereal pack\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fib-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fib-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fib-blade-mcp/lists"}