IBKR MCP Server

An Interactive Brokers (IBKR) MCP server implementation based on FastMCP 2.0 and MCP StreamableHTTP, providing account management, trading operations, and market data query functionality.

Features

• 🔗 Connection Management: Stable connection with IBKR TWS/Gateway
• 📊 Account Information: Query account summary, positions, and balances
• 💹 Trading Operations: Place orders, cancel orders, query order status
• 📈 Market Data: Real-time and historical market data retrieval
• 🛡️ Type Safety: Data validation using Pydantic
• ⚡ Async Architecture: High-performance asynchronous I/O operations
• 📝 Rich Logging: Structured logging
• 🔧 Flexible Configuration: Support for environment variables and configuration files

Installation

Install from Source

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

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install the package
pip install -e .

Development Setup

# Install development dependencies
pip install -e ".[dev]"

# Setup pre-commit hooks
pre-commit install

Quick Start

1. Configure Environment

Create a .env file in the project root:

# MCP Server Settings
MCP__HOST=0.0.0.0
MCP__PORT=8080

# IBKR Connection Settings
IBKR__HOST=127.0.0.1
IBKR__PORT=4002
IBKR__CLIENT_ID=1
IBKR__READONLY=false

# Logging Settings
LOGGING__LEVEL=INFO

2. Test Connection

# Test IBKR connection
python -m ibkr_mcp_server.cli test --host 127.0.0.1 --port 4002

3. Start Server

# Start server
python -m ibkr_mcp_server.cli serve

# Or with custom parameters
python -m ibkr_mcp_server.cli serve --host 0.0.0.0 --port 8080

Configuration

Environment Variables

Variable	Default	Description
MCP__HOST	0.0.0.0	MCP server listen address
MCP__PORT	8080	MCP server port
IBKR__HOST	127.0.0.1	IBKR TWS/Gateway address
IBKR__PORT	4002	IBKR TWS/Gateway port
IBKR__CLIENT_ID	1	IBKR client ID
IBKR__READONLY	false	Read-only mode
LOGGING__LEVEL	INFO	Logging level

IBKR Port Configuration

Platform	Demo Port	Live Port
TWS	4002	7496
Gateway	4002	4001

MCP Tools

The server provides 9 MCP tools:

Account Management

• get_account_summary: Get account summary information
• get_positions: Get position information

Trading Operations

• place_order: Place an order
• cancel_order: Cancel an order
• get_open_orders: Get open orders

Market Data

• get_market_data: Get real-time market data
• get_historical_data: Get historical data

Connection Management

• connection_status: Check connection status
• reconnect: Reconnect to IBKR

Usage Examples

Place Order

{
    "tool": "place_order",
    "arguments": {
        "contract": {
            "symbol": "AAPL",
            "sec_type": "STK",
            "exchange": "SMART",
            "currency": "USD"
        },
        "order": {
            "action": "BUY",
            "total_quantity": 100,
            "order_type": "LMT",
            "lmt_price": 150.0
        }
    }
}

Get Positions

{
    "tool": "get_positions",
    "arguments": {}
}

Get Historical Data

{
    "tool": "get_historical_data",
    "arguments": {
        "contract": {
            "symbol": "AAPL",
            "sec_type": "STK",
            "exchange": "SMART",
            "currency": "USD"
        },
        "duration": "1 D",
        "bar_size": "1 min"
    }
}

Architecture

┌─────────────────────┐
│   MCP Client        │
│ (Claude Desktop,    │
│  Custom Client)     │
└─────────┬───────────┘
          │ HTTP/WebSocket
┌─────────┴───────────┐
│   FastMCP Server    │
│ (MCP Protocol Layer)│
├─────────────────────┤
│   IBKR MCP Server   │
│ (Business Logic)    │
├─────────────────────┤
│   IBKR Client       │
│ (API Wrapper)       │
└─────────┬───────────┘
          │ TWS API
┌─────────┴───────────┐
│   TWS/Gateway       │
│ (IBKR Platform)     │
└─────────────────────┘

Development

Project Structure

src/ibkr_mcp_server/
├── __init__.py          # Package initialization
├── server.py            # MCP server implementation
├── client.py            # IBKR client wrapper
├── models.py            # Data models
├── config.py            # Configuration management
├── exceptions.py        # Exception definitions
└── cli.py              # Command line interface

Code Standards

• Use black for code formatting
• Use isort for import sorting
• Use flake8 for code linting
• Use mypy for type checking

Testing

# Run tests
pytest

# Generate coverage report
pytest --cov=src --cov-report=html

Deployment

Docker Deployment

# Build image
docker build -t ibkr-mcp-server .

# Run container
docker run -p 8080:8080 --env-file .env ibkr-mcp-server

Docker Compose

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "ibkr": {
      "command": "python",
      "args": ["-m", "ibkr_mcp_server.cli", "serve"],
      "env": {
        "IBKR__HOST": "127.0.0.1",
        "IBKR__PORT": "4002",
        "IBKR__CLIENT_ID": "1"
      }
    }
  }
}

Important Notes

1. TWS/Gateway: Ensure IBKR TWS or Gateway is running with API connection enabled
2. Port Configuration: Make sure TWS/Gateway API port matches your configuration
3. Permissions: Ensure your account has appropriate trading permissions
4. Risk Management: Please implement proper risk controls in production environments
5. Market Data: Some market data may require subscriptions

Troubleshooting

Common Issues

1. Connection Failed: Check if TWS/Gateway is running and API is enabled
2. Client ID Conflict: Use different client IDs for multiple connections
3. Port Issues: Verify the correct port for your TWS/Gateway setup
4. Market Data Errors: Ensure you have proper market data subscriptions

Logging

Enable debug logging for troubleshooting:

LOGGING__LEVEL=DEBUG python -m ibkr_mcp_server.cli serve

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues, please file an Issue.

---

中文文档: README_zh_CN.md