IBKR-MCP-Server

A Model Context Protocol (MCP) Server for Interactive Brokers TWS API that enables AI assistants to access portfolio data, account information, and real-time market prices.

Features

• get_portfolio() - Retrieve current portfolio with positions and P&L
• get_account_summary() - Get account balances and key metrics
• get_stock_price(symbol) - Look up current stock prices
• get_option_price(symbol, expiry, strike, right) - Get option prices

Prerequisites

1. Interactive Brokers Account (Paper or Live)
2. TWS (Trader Workstation) or IB Gateway running
3. Python 3.10+

Quick Start

1. Install Dependencies

# Clone and setup
git clone https://github.com/your-username/IBKR-MCP-Server.git
cd IBKR-MCP-Server

# Install with UV (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Or with pip
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .

2. Configure Connection

# Copy example config
cp env.example .env

# Edit .env file:
IBKR_HOST=127.0.0.1
IBKR_PORT=7497              # 7497 for paper, 7496 for live
IBKR_CLIENT_ID=1
IBKR_IS_PAPER=true          # true for paper, false for live

3. Configure TWS

In TWS, go to Configure → Global Configuration → API → Settings:

• ✅ Enable ActiveX and Socket Clients
• ✅ Socket port: 7497 (paper) or 7496 (live)
• ❌ Read-Only API (must be disabled)

4. Test Setup

# Test connection
uv run python test_connection.py

5. Run Server

# Start the MCP server
uv run python src/ibkr_mcp/server.py

6. Claude Desktop Integration

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

{
  "mcpServers": {
    "ibkr": {
      "command": "uv",
      "args": ["run", "python", "src/ibkr_mcp/server.py"],
      "cwd": "/path/to/IBKR-MCP-Server",
      "env": {
        "IBKR_PORT": "7497",
        "IBKR_IS_PAPER": "true"
      }
    }
  }
}

Usage Examples

• "Analyze my current portfolio performance"
• "What's the current price of AAPL and MSFT?"
• "Show me my account summary"

Troubleshooting

Connection Issues:

• Ensure TWS/IB Gateway is running
• Check API settings are enabled in TWS
• Verify correct port (7497 vs 7496)

Permission Issues:

• Disable "Read-Only API" in TWS settings
• Enable API in TWS global configuration

⚠️ Disclaimer: This software is for educational purposes. Use at your own risk. Start with paper trading.