suchi-thamarai/ibkr-portfolio-mcp

IBKR Portfolio MCP Server

Model Context Protocol server for Interactive Brokers account access

Enables AI agents (like Claude) to access your IBKR portfolio, account balance, margin requirements, and market data during conversations. Built on TradingCore for reliable IBKR connectivity.

Features

🔍 Account Monitoring

• Real-time account balance and buying power
• Margin requirements and usage
• Unrealized and realized P&L

📊 Portfolio Analysis

• Current positions with entry prices
• Live market values and P&L by position
• Percentage gains/losses

📈 Market Data

• Historical OHLCV data for any symbol
• Support for stocks, futures, forex, and more
• Flexible timeframes and bar sizes

📋 Order Tracking

• Active orders and their status
• Fill prices and quantities
• Order types (limit, market, stop)

⚡ Order Execution ⚠️ NEW!

• Place market, limit, and stop orders
• Real-time price checks before execution
• Order status monitoring
• Cancel individual or all orders
• Safety confirmations built-in

💬 Web Dashboard & Chat Interface ⚠️ NEW!

• Beautiful web UI for portfolio monitoring
• Conversational AI trading assistant
• Natural language order placement
• Remote access via Tailscale VPN
• Real-time account updates

Prerequisites

1. TradingCore - Must be installed and configured

   git clone https://github.com/YoungMoneyInvestments/TradingCore
   cd TradingCore
   make quick-start
   

2. Interactive Brokers

   • TWS (Trader Workstation) or IB Gateway running
   • API connections enabled in TWS/Gateway settings
   • Port 7497 (paper) or 7496 (live) open

3. Claude Desktop (or any MCP client)

Installation

1. Clone this repository

cd ~
git clone https://github.com/YoungMoneyInvestments/ibkr-portfolio-mcp
cd ibkr-portfolio-mcp

2. Install dependencies

pip install -e .

3. Configure environment

cp .env.example .env
nano .env  # Edit with your TradingCore path

In .env:

TRADING_CORE_PATH=/Users/yourname/TradingCore

4. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ibkr-portfolio": {
      "command": "python",
      "args": [
        "/Users/yourname/ibkr-portfolio-mcp/ibkr_mcp_server.py"
      ],
      "env": {
        "TRADING_CORE_PATH": "/Users/yourname/TradingCore"
      }
    }
  }
}

Important: Replace /Users/yourname/ with your actual home directory path.

5. Restart Claude Desktop

The MCP server will automatically connect when Claude needs IBKR data.

Usage

Start TWS/Gateway First

IMPORTANT: Make sure TWS or IB Gateway is running before using the MCP server.

Paper Trading (recommended for testing):

• Port: 7497
• Configure in TradingCore's config/.env

Live Trading:

• Port: 7496
• ⚠️ Use with caution - real money!

Ask Claude About Your Portfolio

Once configured, you can ask Claude questions like:

Account Information:

• "What's my account balance and buying power?"
• "How much margin am I using?"
• "Show me my unrealized P&L"

Portfolio Analysis:

• "What positions do I currently hold?"
• "Which position has the biggest gain/loss?"
• "What's my total portfolio value?"

Market Data:

• "Get me the latest price for SPY"
• "Show me 1-hour bars for ES futures"
• "What was the price action on AAPL last week?"

Order Management:

• "Do I have any open orders?"
• "Show me my pending limit orders"

Strategy Discussion:

• "I'm thinking of adding a position in TSLA - do I have enough buying power?"
• "Given my current margin usage, should I reduce exposure?"

Web Dashboard & Trading Interface 🆕

Access your portfolio through a beautiful web interface with conversational trading:

./start_web.sh

Access:

• Local: http://localhost:8000
• Remote (Tailscale): http://:8000

Features:

1. Portfolio Dashboard

   • Real-time account balance and buying power
   • Current positions with P&L
   • Open orders tracking

2. Quick Trade Form

   • Place market, limit, and stop orders
   • Real-time price display
   • Safety confirmations

3. Conversational Trading Assistant

   • Natural language commands: "What's the price of AAPL?"
   • Order placement: "Buy 10 shares of TSLA"
   • Portfolio queries: "Show my positions"
   • Account info: "What's my balance?"

⚠️ IMPORTANT: Read TRADING_SAFETY.md before executing any trades!

Setup Guide:

• See REMOTE_ACCESS.md for Tailscale setup
• See TWS_API_SETUP.md for TWS configuration
• See TRADING_SAFETY.md for risk management

Available MCP Tools

The server exposes these tools to AI agents:

Architecture

┌─────────────────┐
│  Claude/AI      │
│  Agent          │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────┐
│  IBKR MCP       │
│  Server         │
└────────┬────────┘
         │ Python Import
         ▼
┌─────────────────┐
│  TradingCore    │
│  IBKRManager    │
└────────┬────────┘
         │ ib_insync
         ▼
┌─────────────────┐
│  TWS / IB       │
│  Gateway        │
└─────────────────┘

Security

🔒 Credentials

• Never commit .env files
• IBKR credentials stored in TradingCore's config/.env
• MCP server has read-only access (no trading execution)

⚠️ Paper vs Live

• Default: Paper trading (port 7497)
• Live trading requires explicit port change to 7496
• Always test with paper account first

Troubleshooting

"Failed to import TradingCore"

• Verify TRADING_CORE_PATH in .env
• Check TradingCore is properly installed
• Make sure TradingCore's venv is activated if using one

"Not connected to IBKR"

• Ensure TWS/IB Gateway is running
• Check port number (7497 for paper, 7496 for live)
• Verify API connections enabled in TWS settings
• Check TradingCore's config/.env has correct IBKR settings

"No account data available"

• Wait a few seconds after connecting
• Try running a test script with TradingCore directly
• Check TWS/Gateway logs for errors

MCP Server Not Showing in Claude

• Verify claude_desktop_config.json syntax
• Check file paths are absolute (not relative)
• Restart Claude Desktop completely
• Check Claude's logs: ~/Library/Logs/Claude/mcp*.log

Development

Run Tests

pytest tests/

Format Code

black ibkr_mcp_server.py

Manual Testing

# Test connection
python -c "from trading_core.ibkr_manager import IBKRManager; m = IBKRManager(); m.connect(); print(m.get_account_summary())"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly with paper trading
5. Submit a pull request

License

MIT

Disclaimer

Use at your own risk. This software connects to your Interactive Brokers account. While the MCP server is read-only (no order execution), always use paper trading for testing. The authors are not responsible for any trading losses or account issues.

Related Projects

• TradingCore - Core trading infrastructure
• Model Context Protocol - MCP specification
• ib_insync - Interactive Brokers API wrapper

Questions? Open an issue on GitHub.