iflow-mcp_gaochx_ibkr-mcp-server 0.1.0

Interactive Brokers MCP Server for account management, trading operations, and market data

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