ibkr-mcp-server

MCP server for Interactive Brokers — Flex Web Service account historical analysis.

Overview

This server exposes IBKR's Flex Web Service as MCP tools so that Claude (or any MCP-compatible client) can retrieve and analyse your account history without manual report downloads.

Prerequisites

1. An Interactive Brokers account.
2. A Flex Query configured in Account Management with the desired sections (Trades, OpenPositions, CashTransactions, EquitySummaryInBase, FIFOPerformanceSummaryInBase).
3. A Flex Web Service token generated in Account Management → Reports → Flex Queries → Manage → Generate Token.

Setup

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

Copy .env.example to .env and fill in your credentials:

cp .env.example .env
# edit .env with your IBKR_FLEX_TOKEN and IBKR_FLEX_QUERY_ID

Running the server

# stdio transport (for Claude Desktop / mcp CLI)
ibkr-mcp

# Or via uv
uv run ibkr-mcp

Claude Desktop config (local stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ibkr": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/ibkr-mcp", "ibkr-mcp"],
      "env": {
        "IBKR_FLEX_TOKEN": "your_token",
        "IBKR_FLEX_QUERY_ID": "your_query_id"
      }
    }
  }
}

claude.ai MCP connector (remote SSE)

claude.ai (Teams / Enterprise) supports custom MCP connectors over HTTPS. The server must be publicly reachable; use the steps below.

1. Deploy the server

# Option A — Docker (recommended)
docker build -t ibkr-mcp .
docker run -d \
  -e IBKR_FLEX_TOKEN=your_token \
  -e IBKR_FLEX_QUERY_ID=your_query_id \
  -e MCP_TRANSPORT=sse \
  -e MCP_AUTH_TOKEN=your_secret_token \
  -p 8000:8000 \
  ibkr-mcp

# Option B — uv directly (on a VPS / cloud VM)
MCP_TRANSPORT=sse \
MCP_AUTH_TOKEN=your_secret_token \
IBKR_FLEX_TOKEN=your_token \
IBKR_FLEX_QUERY_ID=your_query_id \
uv run ibkr-mcp

2. Put HTTPS in front (required by claude.ai)

Use any reverse proxy that terminates TLS. A minimal Caddy example:

your-domain.com {
    reverse_proxy localhost:8000
}

Or use a managed tunnel for quick testing:

ngrok http 8000   # gives you https://xxxx.ngrok.io

3. Add to claude.ai

1. Open claude.ai → Settings → Integrations → Add custom integration
2. Fill in:
   • Name: IBKR
   • URL: https://your-domain.com/sse (note the /sse path)
3. Under Authorization, select Bearer token and paste the value of MCP_AUTH_TOKEN
4. Click Save — the tools appear automatically

Health check: GET https://your-domain.com/health returns {"status":"ok"} and bypasses bearer auth, so you can verify connectivity without credentials.

Available Tools

Flex Web Service protocol

Tool	Description
flex_send_request	Initiate a Flex query; returns a reference_code
flex_get_statement	Download a completed report by reference code (polls until ready)
flex_run_query	Convenience: send + poll + download in one call

XML parsing

Tool	Description
flex_account_info	Account metadata (account ID, type, currency, date range)
flex_parse_trades	Trade records — filterable by symbol, asset category, date
flex_parse_positions	Open position records
flex_parse_cash_txns	Cash transactions (dividends, interest, fees, etc.)
flex_parse_equity	Daily NAV / equity summary time series
flex_parse_fifo_pnl	FIFO realized and unrealized P&L by symbol

Analysis

Tool	Description
flex_analyze_pnl	Aggregate realized P&L from trades; group by symbol, month, year, asset category
flex_analyze_dividends	Summarize gross dividends and withholding taxes by symbol
flex_analyze_portfolio_history	Portfolio value over time with total-return calculation

Typical workflow

1. flex_run_query()                    → xml_content
2. flex_account_info(xml_content)      → account metadata
3. flex_analyze_pnl(xml_content)       → realized P&L by symbol
4. flex_analyze_dividends(xml_content) → dividend income summary
5. flex_analyze_portfolio_history(xml_content) → NAV time series

Flex Query setup guide

Your query must include these Sections for full tool coverage:

• Account Information
• Trades (select Executions)
• Open Positions
• Cash Transactions
• Equity Summary in Base Currency
• FIFO Performance Summary in Base Currency

Recommended date period: Last N days or Custom Date Range covering your analysis window.

Development

uv sync --dev
pytest tests/