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
• One-shot CLI: Per-command connect-execute-disconnect for quick scripting
• Automated TWS Launch (macOS): One command to start TWS and auto-fill TOTP 2FA
• Claude Code Skill: Natural-language trading via the bundled skills/ibkr-trading
• 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

1. Clone the repository:

   git clone https://github.com/happy-shine/ibkr_mcp.git
   cd ibkr_mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. 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

4. Configure the server:

   cp config/config.yaml.example config/config.yaml
   # Edit config/config.yaml with your settings
   

🚀 Usage

Option A: MCP Server

python run.py

The server will:

1. Connect to TWS/IB Gateway
2. Start the MCP server on the configured port
3. Begin heartbeat monitoring
4. Log all activities

Option B: One-shot CLI

Lightweight CLI that connects per command and exits — good for shell scripts or ad-hoc queries.

python cli.py positions
python cli.py summary
python cli.py quote AAPL
python cli.py history AAPL --duration "1 M" --bar "1 day"
python cli.py buy AAPL 10 --type MKT --confirm
python cli.py orders

Run python cli.py --help for the full command list.

Note on quote data: If you do not have a live market-data subscription, quote falls back to the most recent daily bar via historical data (no real-time fields).

Option C: Automated TWS Launch (macOS only)

start_tws.py launches TWS via IBC, detects the Second-Factor Authentication dialog, generates a TOTP code with pyotp, and types it in through AppleScript (osascript) — fully automated login without touching the keyboard.

python start_tws.py          # launch and auto-fill 2FA
python start_tws.py --wait   # also block until API port 7496 is listening

Requirements (macOS):

Component	Purpose	Link
IBC	Automates TWS launch & login inputs	https://github.com/IbcAlpha/IBC
pyotp	RFC 6238 TOTP code generation	https://github.com/pyauth/pyotp
osascript / AppleScript	Ships with macOS; drives the 2FA dialog	built-in

Setup:

1. Install IBC per its macOS instructions (typically at ~/ibc/).
2. In ~/ibc/config.ini, set:
   • TradingMode=live (or paper)
   • SecondFactorDevice=Mobile Authenticator
   • Your IBKR credentials
3. Save your IBKR TOTP secret (the Base32 string from the authenticator QR code) to ~/.ibkr-totp-secret or export it as TOTP_SECRET.
4. Grant Terminal (or your Python launcher) Accessibility permission in System Settings → Privacy & Security → Accessibility — required for AppleScript to interact with the TWS window.

Platform note: start_tws.py relies on AppleScript/osascript and is macOS only. Linux/Windows users should either use IBC directly or adapt the GUI-automation layer (e.g. xdotool on Linux, pywinauto on Windows).

Available MCP Tools

Account Tools

• get_positions() - Get current account positions
• get_account_summary() - Get account balance and metrics
• get_portfolio() - Get detailed portfolio information

Market Data Tools

• get_historical_data(symbol, duration, bar_size) - Get historical price data
• get_market_data(symbol) - Get real-time market data
• get_quote_from_history(symbol) - Last daily bar as a quote (no subscription needed)
• get_contract_details(symbol) - Get contract specifications
• get_option_chain - Get Option data

Trading Tools

• place_order(symbol, action, quantity, order_type, ...) - Place buy/sell orders
• get_orders(status) - Get order history and status
• cancel_order(order_id) - Cancel pending orders
• get_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")

🤖 Claude Code Skill

A companion skill lives at skills/ibkr-trading/SKILL.md. It lets Claude Code dispatch the CLI commands above from natural-language prompts (e.g. "show my positions", "quote AAPL").

To install, symlink it into your Claude Code skills directory:

ln -s "$(pwd)/skills/ibkr-trading" ~/.claude/skills/ibkr-trading

🔗 Related Links & Credits

• Interactive Brokers TWS API — official Python API (ibapi)
• IBC — Interactive Brokers Controller — TWS auto-launcher (used by start_tws.py)
• pyotp — TOTP/HOTP library (used by start_tws.py)
• Model Context Protocol Specification
• FastMCP Framework
• Claude Code — AI pair-programming CLI that consumes the bundled skill