IBKR MCP Server
A Model Context Protocol (MCP) server that provides AI models with secure access to Interactive Brokers (IBKR) trading data and functionality through the TWS API.
⚠️⚠️⚠️ Disclaimer ⚠️⚠️⚠️
This software is for educational and development purposes. Use at your own risk. The authors are not responsible for any financial losses incurred through the use of this software. Always test with paper trading before using with real money.
🚀 Features
- Account Management: Get positions, portfolio details, and account summaries
- Market Data: Retrieve historical price data and real-time market information
- Trading Operations: Place orders, manage positions, and track executions
- MCP Integration: Seamless integration with AI models supporting MCP protocol
- Safety Features: Read-only mode, configurable trading restrictions, and comprehensive validation
- High Availability: Automatic reconnection, heartbeat monitoring, and graceful error handling
📋 Prerequisites
- Python 3.10+
- Interactive Brokers TWS or IB Gateway
- Active IBKR account (paper trading recommended for testing)
🛠️ Installation
-
Clone the repository:
git clone https://github.com/happy-shine/ibkr_mcp.git cd ibkr_mcp -
Install dependencies:
pip install -r requirements.txt -
Configure TWS/IB Gateway:
- Enable API connections in TWS/Gateway settings
- Set socket port (default: 7497 for paper trading, 7496 for live)
- Configure trusted IP addresses if needed
-
Configure the server:
cp config/config.yaml.example config/config.yaml # Edit config/config.yaml with your settings
🚀 Usage
Starting the Server
# Using the run script
python run.py
The server will:
- Connect to TWS/IB Gateway
- Start the MCP server on the configured port
- Begin heartbeat monitoring
- Log all activities
Available MCP Tools
Account Tools
get_positions()- Get current account positionsget_account_summary()- Get account balance and metricsget_portfolio()- Get detailed portfolio information
Market Data Tools
get_historical_data(symbol, duration, bar_size)- Get historical price dataget_market_data(symbol)- Get real-time market dataget_contract_details(symbol)- Get contract specificationsget_option_chain- Get Option data
Trading Tools
place_order(symbol, action, quantity, order_type, ...)- Place buy/sell ordersget_orders(status)- Get order history and statuscancel_order(order_id)- Cancel pending ordersget_trades()- Get execution history
Example AI Interactions
AI: "What are my current positions?"
→ Calls get_positions() tool
AI: "Buy 100 shares of AAPL at market price"
→ Calls place_order(symbol="AAPL", action="BUY", quantity=100, order_type="MKT")
AI: "Show me AAPL's price history for the last week"
→ Calls get_historical_data(symbol="AAPL", duration="1 W", bar_size="1 day")