# Interactive Brokers MCP Server for Windows
A Model Context Protocol (MCP) server that provides tools for interacting with Interactive Brokers (IBKR) through the TWS API or IB Gateway.
## Features
- **Account Management**: Get account summary, positions, and portfolio information
- **Market Data**: Real-time and historical market data for stocks
- **Order Management**: Place market and limit orders, cancel orders, view open orders
- **Trade Execution**: View recent trade executions
- **Options Trading**: Get option chains for stocks
## Prerequisites
1. **Interactive Brokers Account**: You need an active IBKR account
2. **TWS or IB Gateway**: Install either:
- Trader Workstation (TWS) - Full trading platform
- IB Gateway - Lightweight API gateway
Download from: https://www.interactivebrokers.com/en/trading/tws.php
3. **Python 3.8+**: Required for running the MCP server
4. **Enable API Access**: In TWS/Gateway settings:
- File → Global Configuration → API → Settings
- Enable "Enable ActiveX and Socket Clients"
- Note the Socket port (7497 for paper trading, 7496 for live)
- Add 127.0.0.1 to trusted IPs
## Installation
### Step 1: Install Python Dependencies
Open Command Prompt or PowerShell and run:
```bash
pip install -r requirements.txt
```
Or install packages individually:
```bash
pip install mcp ib_insync pydantic
```
### Step 2: Configure TWS/IB Gateway
1. Start TWS or IB Gateway
2. Log in with your credentials
3. Go to: **File → Global Configuration → API → Settings**
4. Check "Enable ActiveX and Socket Clients"
5. Uncheck "Read-Only API" if you want to place orders
6. Note the Socket Port:
- **7497** for Paper Trading
- **7496** for Live Trading
7. Add **127.0.0.1** to Trusted IPs
8. Click **OK** and restart TWS/Gateway
## Usage
### Starting the MCP Server
```bash
python server.py
```
The server will run and wait for MCP client connections via stdio.
### Integrating with Claude Desktop
Add this configuration to your Claude Desktop config file:
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"ibkr": {
"command": "python",
"args": ["C:\\path\\to\\ibkr-mcp-server\\server.py"]
}
}
}
```
Replace `C:\\path\\to\\ibkr-mcp-server\\` with the actual path where you saved this project.
### Available Tools
#### 1. **connect_ibkr**
Connect to Interactive Brokers TWS or Gateway.
```json
{
"host": "127.0.0.1",
"port": 7497,
"client_id": 1
}
```
- `port`: 7497 (paper trading) or 7496 (live trading)
- Must be called before using other tools
#### 2. **disconnect_ibkr**
Disconnect from IBKR.
#### 3. **get_account_summary**
Get account summary including cash, equity, and P&L.
Returns:
```json
{
"TotalCashValue": "50000.00 USD",
"NetLiquidation": "52000.00 USD",
"BuyingPower": "200000.00 USD",
"RealizedPnL": "500.00 USD",
"UnrealizedPnL": "2000.00 USD"
}
```
#### 4. **get_positions**
Get all current positions.
Returns array of positions with symbol, quantity, avg cost, market value, and P&L.
#### 5. **get_market_data**
Get real-time market data for a symbol.
```json
{
"symbol": "AAPL",
"exchange": "SMART",
"currency": "USD"
}
```
Returns bid, ask, last, volume, high, low prices.
#### 6. **get_historical_data**
Get historical market data.
```json
{
"symbol": "AAPL",
"duration": "1 D",
"bar_size": "1 hour",
"what_to_show": "TRADES"
}
```
Duration options: "1 D", "1 W", "1 M", "1 Y"
Bar size options: "1 min", "5 mins", "1 hour", "1 day"
#### 7. **place_order**
Place a trading order.
Market Order:
```json
{
"symbol": "AAPL",
"action": "BUY",
"quantity": 100,
"order_type": "MKT"
}
```
Limit Order:
```json
{
"symbol": "AAPL",
"action": "SELL",
"quantity": 100,
"order_type": "LMT",
"limit_price": 150.50
}
```
#### 8. **cancel_order**
Cancel an existing order.
```json
{
"order_id": 123
}
```
#### 9. **get_open_orders**
Get all open orders.
#### 10. **get_executions**
Get recent trade executions.
```json
{
"days": 1
}
```
#### 11. **get_option_chain**
Get option chain for a symbol.
```json
{
"symbol": "AAPL",
"exchange": "SMART"
}
```
## Example Conversations with Claude
Once configured, you can ask Claude:
- "Connect to my IBKR paper trading account"
- "What's my current account balance?"
- "Show me all my positions"
- "Get the current price of AAPL"
- "Show me historical data for TSLA over the last week"
- "Place a market order to buy 10 shares of MSFT"
- "What are my open orders?"
- "Get the option chain for SPY"
## Security Notes
⚠️ **Important Security Considerations:**
1. **Paper Trading First**: Always test with paper trading (port 7497) before using live account
2. **Order Confirmation**: The server allows order placement - use with caution
3. **API Access**: Only enable API access when actively using it
4. **Firewall**: Ensure your firewall allows connections to TWS/Gateway
5. **Credentials**: Never share your IBKR credentials or API keys
## Troubleshooting
### Connection Failed
- Ensure TWS or IB Gateway is running
- Verify API settings are enabled
- Check port number (7497 for paper, 7496 for live)
- Confirm 127.0.0.1 is in trusted IPs
### No Market Data
- Your IBKR account needs market data subscriptions
- Real-time data requires active subscriptions
- Delayed/snapshot data may be available without subscription
### Order Placement Fails
- Ensure "Read-Only API" is unchecked in TWS settings
- Verify you have sufficient buying power
- Check that the market is open for the security
### Module Not Found
```bash
pip install --upgrade mcp ib_insync pydantic
```
## Development
### Running Tests
```bash
python -m pytest tests/
```
### Logging
Logs are written to console. Adjust logging level in `server.py`:
```python
logging.basicConfig(level=logging.DEBUG)
```
## License
MIT License - See LICENSE file for details
## Disclaimer
This software is for educational purposes. Trading involves risk. Use at your own discretion. The authors are not responsible for any financial losses.
## Resources
- [Interactive Brokers API](https://interactivebrokers.github.io/)
- [ib_insync Documentation](https://ib-insync.readthedocs.io/)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [IBKR API Reference](https://interactivebrokers.github.io/tws-api/)
## Support
For issues related to:
- **IBKR API**: Contact Interactive Brokers support
- **MCP Server**: Open an issue on GitHub
- **ib_insync**: Check the ib_insync documentation
## Changelog
### Version 1.0.0
- Initial release
- Support for basic account operations
- Market data retrieval
- Order management
- Historical data queries
- Option chain retrieval
