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 informationget_positions: Get position information
Trading Operations
place_order: Place an ordercancel_order: Cancel an orderget_open_orders: Get open orders
Market Data
get_market_data: Get real-time market dataget_historical_data: Get historical data
Connection Management
connection_status: Check connection statusreconnect: 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
blackfor code formatting - Use
isortfor import sorting - Use
flake8for code linting - Use
mypyfor 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
- TWS/Gateway: Ensure IBKR TWS or Gateway is running with API connection enabled
- Port Configuration: Make sure TWS/Gateway API port matches your configuration
- Permissions: Ensure your account has appropriate trading permissions
- Risk Management: Please implement proper risk controls in production environments
- Market Data: Some market data may require subscriptions
Troubleshooting
Common Issues
- Connection Failed: Check if TWS/Gateway is running and API is enabled
- Client ID Conflict: Use different client IDs for multiple connections
- Port Issues: Verify the correct port for your TWS/Gateway setup
- 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
Metadata
Release files for iflow-mcp_gaochx_ibkr-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_gaochx_ibkr_mcp_server-0.1.0.tar.gz | 17.1 kB | Without provenance | Details for iflow_mcp_gaochx_ibkr_mcp_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_gaochx_ibkr_mcp_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_gaochx_ibkr_mcp_server-0.1.0-py3-none-any.whl |
Total release size: 35.8 kB
Release files / iflow_mcp_gaochx_ibkr_mcp_server-0.1.0.tar.gz
| Download URL | iflow_mcp_gaochx_ibkr_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ef6b6742a4e699f2ed8780b4ceb35720332c001dd7dcba110b484da1ee47ccc
|
|
BLAKE2b-256 checksum How to use checksums |
642fc8243c45429c6f7e24b618b5e4d27c870b924beab5a76c64f747eab7c22a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.25 {"installer":{"name":"uv","version":"0.9.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_gaochx_ibkr_mcp_server-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_gaochx_ibkr_mcp_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 18.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0b9bbd4eb5d67ca36630ed1528603990258055a57568dea35c04c05b311012c3
|
|
BLAKE2b-256 checksum How to use checksums |
e630bdb93f5be461788cc3851fd0f5492c27c07edbf7ce34bc36c5aeff86baa8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.25 {"installer":{"name":"uv","version":"0.9.25","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_gaochx_ibkr-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.