IBKR Portfolio Builder

Top-down portfolio research for Interactive Brokers with typed catalog of 468 IBKR screeners tagged by strategy intent. Read-only.

A remote MCP server fortop-down portfolio construction with Interactive Brokers. Built to be used as a Claude.ai custom connector, Claude Code MCP, or any HTTP MCP client.

Most ibkr-mcp servers expose individual lookup primitives —get_quote,get_position,place_order. This one exposes theresearch workflow: a typed catalog of 468 screeners across 16 categories tagged by strategy intent (value / growth / income / momentum / quality / events / …), per-scan applicable instruments, inverse-pair links, and live news/account access — so an LLM can do real top-down portfolio construction (pick sectors / strategies → run scans → cross-reference with news → narrow to candidates) instead of bottoms-up ticker fishing.

I built this because the existing IBKR-MCP servers in the community treat IBKR as a "look-up-one-ticker" data source. That mirrors how most retail brokerage UIs work, but it's not how good portfolio construction actually happens.
- Macro thesis("rates are about to fall, dividend payers should re-rate") →
- Strategy intent("show me income screens with quality bias on US large caps") →
- Screener composition(run dividend yield + ROE + low debt screens; intersect) →
- Event/news context("any of these have earnings in the next two weeks? any negative analyst actions?") →
- Narrow candidate set("five tickers, ranked by my criteria, ready for deeper diligence").

To do that with an LLM, the MCP server needs to exposethe research vocabulary, not just the raw API. That's the gap this server fills:

- A typed scan catalog— 468 IBKR scan codes across 16 categories (Fundamentals,Price Movement,Dividends,Options & Volatility,Events & Earnings,52/26/13 Week High-Low,ESG,Bonds, …) auto-tagged with28 strategy intent tags(value,growth,quality,income,momentum_up,momentum_down,analyst,technical,gap,volatility,events,leverage,efficiency,risk_adjusted, …). The LLM asks "what value scans exist for US stocks?" and gets a clean, filterable answer instead of trying to guess scan codes from training data.
- Inverse pair links— everyHIGH_X ↔ LOW_XandX_ASC ↔ X_DESCpair is precomputed, so the LLM can flip polarity ("what's the opposite of LOW_PE_RATIO?") without guessing.
- Per-scan instrument map— the catalog knows which scan applies toSTK,ETF,OPT,BOND, etc. The LLM stops sending Refinitiv scans to bond instruments and getting empty results.
- Filter catalog— separate typed map of the numeric filters (priceAbove,peRatioBelow,divYieldAbove,growthRateAbove,avgVolumeAbove,marketCapAbove, …) grouped by category, with per-instrument applicability notes.
- News + screeners in one tool surface— same connector, same auth, same conversation. The LLM can intersect a scan result with recent headlines or upcoming earnings without context-switching.
- Two auth modes— full OAuth 2.1 (DCR + PKCE + well-knowns) for Claude.ai custom connectors, plus a static bearer token for everything else. Same server, same tools.

It's still an early server. The IBKR API has plenty of restrictions on what a paper account can actually see (notably historical news entitlement). But thecatalogandworkflow shapeare production-ready, and they're the load-bearing piece for an LLM-driven research loop.

- Transport:Streamable HTTP at/mcp.
- Auth:OAuth 2.1 (PKCE + RFC 7591 Dynamic Client Registration) AND/OR static bearer token. Selectable viaAUTH_MODE.
- Persistence:in-memory only today (sessions / DCR clients / OAuth tokens reset on container restart). Redis is on the roadmap — see below.
- IBKR connection:ib-gateway (ghcr.io/gnzsnz/ib-gateway:stable) runs as a sibling service in this compose; paper account in read-only API mode by default.
- Built on:FastMCP+ib_async.

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

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"}'

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

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

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

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

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."

. ├── 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

- gnzsnz/ib-gateway-dockerfor the headless ib-gateway image.
- ib_asyncfor the async IBKR client.
- FastMCPfor the MCP server framework with built-in OAuth support.

Coinrule Agentic Trading MCP enables investors to create, backtest, execute, and manage trading agents through natural language across stocks, crypto and ETFs