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.
get_portfolio()- Retrieve current portfolio with positions and P&Lget_account_summary()- Get account balances and key metricsget_stock_price(symbol)- Look up current stock pricesget_option_price(symbol, expiry, strike, right)- Get option prices
- Interactive Brokers Account (Paper or Live)
- TWS (Trader Workstation) or IB Gateway running
- Python 3.10+
# 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 .# 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 liveIn 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)
# Test connection
uv run python test_connection.py# Start the MCP server
uv run python src/ibkr_mcp/server.pyAdd 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"
}
}
}
}- "Analyze my current portfolio performance"
- "What's the current price of AAPL and MSFT?"
- "Show me my account summary"
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