IBKR MCP Server

A professional Model Context Protocol (MCP) server for Interactive Brokers API integration, designed for use with Claude Desktop and Claude Code.

Features

• ✅ Multi-Account Support - Switch between multiple IBKR accounts
• ✅ Short Selling Analysis - Shortable shares, borrow rates, margin requirements
• ✅ Real-time Market Data - Live quotes, historical data, options chains
• ✅ Portfolio Management - Positions, P&L, account summaries
• ✅ Trading Operations - Place, modify, cancel orders (with safety checks)
• ✅ Auto-Reconnection - Handles TWS/Gateway restarts gracefully
• ✅ Production Ready - Proper error handling, logging, and monitoring

Quick Start

Prerequisites

• Python 3.10 or higher
• Interactive Brokers account with TWS or IB Gateway
• Claude Desktop or Claude Code

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/ibkr-mcp-server.git
   cd ibkr-mcp-server
   

2. Run the setup script:

   # macOS/Linux
   chmod +x scripts/setup.sh
   ./scripts/setup.sh
   
   # Windows
   scripts\setup.bat
   

3. Configure your settings:

   cp .env.example .env
   # Edit .env with your IBKR settings
   

4. Start TWS/IB Gateway and enable API connections

5. Test the server:

   python -m ibkr_mcp_server.main --test
   

Claude Integration

Claude Desktop: Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ibkr": {
      "command": "python",
      "args": ["-m", "ibkr_mcp_server.main"],
      "cwd": "/path/to/ibkr-mcp-server"
    }
  }
}

Claude Code:

claude mcp add ibkr 'python -m ibkr_mcp_server.main' --cwd /path/to/ibkr-mcp-server

Usage Examples

Basic Operations

# Get portfolio across all accounts
"Show me my current portfolio"

# Switch accounts
"Switch to account DU7654321"

# Market data
"Get real-time quotes for AAPL, TSLA, MSFT"

Short Selling Analysis

# Complete short selling analysis
"Analyze short selling for GME, AMC, BBBY - show availability, borrow costs, and margin requirements"

# Check specific account
"Check shortable shares for TSLA in my paper trading account"

Trading Operations

# Place orders (paper trading recommended)
"Place a limit order to buy 100 shares of AAPL at $150"

# Check margin requirements
"What are the margin requirements for shorting 200 shares of TSLA?"

Available Tools

Tool	Description
get_portfolio	Current portfolio positions and P&L
get_account_summary	Account balances and key metrics
switch_account	Switch between IBKR accounts
check_shortable_shares	Short selling availability
get_margin_requirements	Margin requirements for securities
get_borrow_rates	Stock borrow rates (short selling costs)
short_selling_analysis	Complete short selling analysis
get_market_data	Real-time market quotes
get_historical_data	Historical price data
place_order	Place trading orders (with safety checks)
get_connection_status	Check IBKR connection status

Configuration

Environment Variables

# IBKR Connection
IBKR_HOST=127.0.0.1
IBKR_PORT=7497  # 7497=TWS Paper, 7496=TWS Live, 4001=Gateway
IBKR_CLIENT_ID=1
IBKR_IS_PAPER=true

# Logging
LOG_LEVEL=INFO

# Safety
ENABLE_LIVE_TRADING=false  # Set to true for live trading
MAX_ORDER_SIZE=1000  # Maximum order size

TWS/Gateway Setup

1. Start TWS or IB Gateway
2. Go to Configuration → API → Settings
3. Enable "ActiveX and Socket Clients"
4. Set socket port (7497 for paper, 7496 for live)
5. Add 127.0.0.1 to "Trusted IPs"
6. Check "Download open orders on connection"

Development

Setup Development Environment

pip install -e ".[dev]"
pre-commit install

Running Tests

pytest tests/ -v

Code Quality

black ibkr_mcp_server/
isort ibkr_mcp_server/
mypy ibkr_mcp_server/

Deployment

Auto-start on Boot (macOS)

python scripts/install_service.py --platform macos

Auto-start on Boot (Linux)

python scripts/install_service.py --platform linux

Docker Deployment

docker build -t ibkr-mcp-server .
docker run -d --name ibkr-mcp -p 8080:8080 ibkr-mcp-server

Documentation

• API Reference
• Deployment Guide
• Troubleshooting

Safety & Disclaimers

⚠️ Important Safety Notes:

• Always test with paper trading first
• Verify all data in TWS before making trading decisions
• This software is for educational purposes
• Use at your own risk
• No warranty provided

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues
• Discussions
• Wiki