ibkr_trade_mcp #

A Model Context Protocol (MCP) server for Interactive Brokers (IBKR), built using the ib_trade_core Dart SDK.

This MCP server provides a standardized JSON-RPC 2.0 interface for AI assistants (such as Claude Desktop, Cursor, or custom LLM agents) to execute trades, manage working orders, inspect portfolio PnL, preview margin impact, and explore option chains via the local IBKR Client Portal Gateway REST API.

🚀 Key Features & Supported MCP Tools #

ibkr_trade_mcp exposes 20 dedicated MCP tools designed for automated trading agents:

👤 Account & Session Management #

• get_session_status: Retrieve active IBKR connection status, authentication state, and logged-in username.
• list_accounts: Fetch all trading accounts associated with the active IBKR session.
• get_positions: Fetch current portfolio positions (stocks, options, cash balances) for an account.
• get_account_summary: Retrieve Net Liquidation Value, buying power, available funds, and total equity.
• get_cash_ledger: Fetch multi-currency cash balances (USD, EUR, GBP, JPY, etc.).
• ibkr_login: Automatically launch browser for local IBKR Client Portal 2FA authentication.
• ibkr_logout: Terminate the active IBKR Client Portal Gateway session.

📈 Order Placement & Execution #

• place_order: Submit trade orders (BUY/SELL) for equities or options with support for LMT, MKT, STP, TRAIL (trailing stop dollar amount), and TRAIL LIMIT (trailing stop percentage) order types.
• place_bracket_order: Orchestrate linked 3-legged bracket orders (Market/Limit Buy entry + Take-Profit + Stop-Loss protective legs).
• reply_to_challenge: Submit confirmation replies (accept/decline) for execution warning challenge prompts returned by IBKR.
• list_working_orders: Fetch open, pending, or working orders across accounts.
• modify_order: Modify price or quantity of active working orders.
• cancel_order: Cancel pending active working orders.

📊 Portfolio PnL & Pre-Trade Preview #

• get_portfolio_pnl: Retrieve aggregated daily PnL, unrealized PnL, realized PnL, Net Liquidation Value, and position breakdown with automatic position-level reconciliation.
• preview_order: Pre-trade order what-if preview returning estimated margin impact, fee bounds, and risk warnings before submitting live orders.

🔍 Market Data & Derivatives Discovery #

• search_contracts: Search IBKR securities (stocks, ETFs, options) by symbol or name to discover contract IDs (conid).
• get_market_data: Retrieve real-time market data snapshots (last price, bid, ask, daily volume).
• get_historical_prices: Retrieve historical candlestick price bars (1min, 5min, 1h, 1d) for technical analysis.
• get_option_chains: Fetch available option expiration dates and strike price matrices for an underlying security.
• resolve_option_contract: Resolve exact option contract IDs (conid) given underlying conid, strike, expiration date, and right (CALL/PUT).

💻 Quick Start Guide #

1. Prerequisites #

• Dart SDK: ^3.0.0
• IBKR Client Portal Gateway: Download and run the local IBKR Client Portal Gateway on https://localhost:5000. Authenticate via browser 2FA.

2. Installation #

Install via Dart Pub:

dart pub add ibkr_trade_mcp

Or activate globally as a CLI executable:

dart pub global activate ibkr_trade_mcp

🤖 Configuration for Claude Desktop #

Connect this MCP server to Claude Desktop by updating your claude_desktop_config.json:

Configuration Path #

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ibkr-trade": {
      "command": "dart",
      "args": [
        "run",
        "ibkr_trade_mcp"
      ],
      "env": {
        "IBKR_GATEWAY_HOST": "localhost",
        "IBKR_GATEWAY_PORT": "5000",
        "IBKR_GATEWAY_SCHEME": "https"
      }
    }
  }
}

🔧 Programmatic Embedding in Dart #

import 'dart:io';
import 'package:ib_trade_core/ib_trade_core.dart';
import 'package:ibkr_trade_mcp/ibkr_trade_mcp.dart';

void main() async {
  final config = GatewayConfig(
    host: 'localhost',
    port: 5000,
    scheme: 'https',
  );

  final client = CookieClient(HttpClient(bypassSslVerification: true));
  final registry = McpToolRegistry(client: client, config: config);
  final server = McpServer(registry);

  print('Starting IBKR Trade MCP Server...');
  await server.start();
}

📄 License #

Distributed under the MIT License. See LICENSE for details.