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.

Related MCP server: IBKR MCP Server

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

XML parsing

Analysis

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/