Interactive Brokers MCP Server

DISCLAIMER: This is an unofficial, community-developed MCP server and is NOT affiliated with or endorsed by Interactive Brokers. This software is in Alpha state and may not work perfectly.

A Model Context Protocol (MCP) server that provides integration with Interactive Brokers' trading platform. This server allows AI assistants to interact with your IB account to retrieve market data, check positions, and place trades.

🔒 Security Notice

Features

• Interactive Brokers API Integration: Full trading capabilities including account management, position tracking, real-time market data, and order management (market, limit, and stop orders)
• Derivatives & Event Contracts: Trade IBKR ForecastTrader prediction markets and options through a contract discovery workflow (search → strikes → info → trade)
• Flex Query Support: Execute Flex Queries to retrieve account statements, trade confirmations, and historical data. Queries are automatically remembered for easy reuse
• Flexible Authentication: Choose between browser-based OAuth authentication or headless mode with credentials for automated environments
• Simple Setup: Run directly with npx - no Docker or additional installations required. Includes pre-configured IB Gateway and Java runtime for all platforms

Security Notice

IMPORTANT WARNINGS:

• Financial Risk: Trading involves substantial risk of loss. Always test with paper trading first.
• Security: This software handles sensitive financial data. Only run locally, never on public servers.
• No Warranty: This unofficial software comes with no warranties. Use at your own risk.
• Not Financial Advice: This tool is for automation only, not financial advice.

Prerequisites

No additional installations required! This package includes:

• Pre-configured IB Gateway for all platforms (Linux, macOS, Windows)
• Java Runtime Environment (JRE) for IB Gateway
• All necessary dependencies

You only need:

• Interactive Brokers account (paper or live trading)
• Node.js 18+ (for running the MCP server)

Quick Start

Add this MCP server to your Cursor/Claude configuration:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"]
    }
  }
}

When you first use the server, a web browser window will automatically open for the Interactive Brokers OAuth authentication flow. Log in with your IB credentials to authorize the connection.

Headless Mode Configuration

For automated environments or when you prefer not to use a browser for authentication, you can enable headless mode by configuring it in your MCP server configuration:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_HEADLESS_MODE": "true",
        "IB_USERNAME": "your_ib_username",
        "IB_PASSWORD_AUTH": "your_ib_password"
      }
    }
  }
}

In headless mode, the server will automatically authenticate using your credentials without opening a browser window. This is useful for:

• Automated trading systems
• Server environments without a display
• CI/CD pipelines
• Situations where browser interaction is not desired

Important: Even in headless mode, Interactive Brokers may still require two-factor authentication (2FA). When 2FA is triggered, the headless authentication will wait for you to complete the 2FA process through your configured method (mobile app, SMS, etc.) before proceeding.

To enable paper trading, add "IB_PAPER_TRADING": "true" to your environment variables:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_HEADLESS_MODE": "true",
        "IB_USERNAME": "your_ib_username",
        "IB_PASSWORD_AUTH": "your_ib_password",
        "IB_PAPER_TRADING": "true"
      }
    }
  }
}

Security Note: Store credentials securely and never commit them to version control. Consider using environment variable files or secure credential management systems.

Persistent Gateway (Systemd Service)

By default, the MCP server starts a local IB Gateway process that dies when the MCP server exits. This means re-authentication (including 2FA) every time. To avoid this, install the gateway as a persistent systemd user service:

cd /path/to/interactive-brokers-mcp
./ib-gateway/install-service.sh --port 5000 --name sienna

This creates two services: ib-gateway-sienna (the gateway) and ib-gateway-sienna-tickle (a keepalive that prevents IBKR session expiry).

Managing the service:

systemctl --user status ib-gateway-sienna        # Check status
journalctl --user -u ib-gateway-sienna -f         # Follow logs
systemctl --user restart ib-gateway-sienna        # Restart gateway
systemctl --user stop ib-gateway-sienna ib-gateway-sienna-tickle  # Stop both

The gateway survives reboots and the tickle loop keeps your IBKR session alive even when no MCP client is connected. See ib-gateway/UNINSTALL.md for removal instructions.

Multi-Account Setup

To run multiple accounts (e.g., live and paper trading), start separate gateways on different ports:

./ib-gateway/install-service.sh --port 5000 --name sienna   # Live account
./ib-gateway/install-service.sh --port 5001 --name vera     # Paper account

Then set IB_GATEWAY_PORT in each MCP client's config:

{
  "mcpServers": {
    "ib-live": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_GATEWAY_PORT": "5000",
        "IB_GATEWAY_HOST": "host.docker.internal"
      }
    },
    "ib-paper": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_GATEWAY_PORT": "5001",
        "IB_GATEWAY_HOST": "host.docker.internal"
      }
    }
  }
}

For Docker/remote containers, set IB_GATEWAY_HOST to the host running the gateway (e.g., host.docker.internal). For local usage, omit it (defaults to localhost).

Flex Query Configuration (Optional)

To use Flex Queries for retrieving account statements and historical data, you need to configure your Flex Web Service Token:

{
  "mcpServers": {
    "interactive-brokers": {
      "command": "npx",
      "args": ["-y", "interactive-brokers-mcp"],
      "env": {
        "IB_FLEX_TOKEN": "your_flex_token_here"
      }
    }
  }
}

How to Get Your Flex Token:

1. Log in to Interactive Brokers Account Management
2. Go to Settings → Account Settings
3. Navigate to Reporting → Flex Web Service
4. Generate or retrieve your Flex Web Service Token

For detailed instructions on enabling Flex Web Service, see the IB Flex Web Service Guide.

Creating Flex Queries:

1. Go to Reports → Flex Queries in Account Management
2. Create or customize your query template
3. Click the info icon next to your query to find its Query ID

For a complete guide on creating and customizing Flex Queries, see the IB Flex Queries Guide.

Note: When you execute a Flex Query for the first time, the MCP server automatically saves it with its name from the API. Future executions can reference the query by either its ID or its saved name.

Flex Query Features:

• Automatic Memory: When you execute a Flex Query, it's automatically saved for future use
• Easy Reuse: Previously used queries are remembered - no need to copy query IDs repeatedly
• Friendly Names: Optionally provide a friendly name when first executing a query
• Forget Queries: Remove queries you no longer need with the forget_flex_query tool

Configuration Variables

| Feature | Environment Variable | Command Line Argument | |---------|---------------------|----------------------| | Username | IB_USERNAME | --ib-username | | Password | IB_PASSWORD_AUTH | --ib-password-auth | | Headless Mode | IB_HEADLESS_MODE | --ib-headless-mode | | Paper Trading | IB_PAPER_TRADING | --ib-paper-trading | | Auth Timeout | IB_AUTH_TIMEOUT | --ib-auth-timeout | | Flex Token | IB_FLEX_TOKEN | N/A | | Read-only mode | IB_READ_ONLY_MODE | --ib-read-only-mode | | Account ID | IB_ACCOUNT | --ib-account | | Gateway Host | IB_GATEWAY_HOST | N/A | | Gateway Port | IB_GATEWAY_PORT | N/A | | Gateway Timeout | IB_GATEWAY_TIMEOUT | N/A | | Market Data Host | IB_MARKET_DATA_HOST | N/A | | Market Data Port | IB_MARKET_DATA_PORT | N/A |

Available MCP Tools

Trading & Account Management

| Tool | Description | | ------------------ | ----------------------------------------- | | get_account_info | Retrieve account information and balances | | get_positions | Get current positions and P&L | | get_market_data | Real-time market data for symbols | | get_historical_data | Historical OHLCV price bars for symbols | | place_order | Place market, limit, or stop orders | | get_order_status | Check order execution status | | get_live_orders | Get all live/open orders for monitoring | | place_bracket_order | Place a bracket order (parent + take-profit + stop-loss) | | cancel_order | Cancel a pending order | | confirm_order | Manually confirm an order requiring confirmation |

Alerts

| Tool | Description | | ------------------ | ----------------------------------------- | | get_alerts | Get all trading alerts for an account | | create_alert | Create a new price or condition alert | | activate_alert | Activate or deactivate an existing alert | | delete_alert | Delete an alert |

Derivatives & Event Contracts (ForecastTrader)

| Tool | Description | | ------------------------- | --------------------------------------------------------------------------- | | search_contracts | Search for derivative contracts (event contracts, options) by symbol | | get_contract_strikes | Get available strike prices for a contract in a given expiration month | | get_contract_info | Get detailed contract info (Yes/No or Call/Put pair) for a specific strike | | get_contract_market_data| Get market data (bid, ask, last, volume) for a specific contract by conid | | place_order_by_conid | Place an order using a resolved contract ID (only if read-only mode is disabled) |

Workflow: search_contracts → get_contract_strikes → get_contract_info → get_contract_market_data / place_order_by_conid

These tools support IBKR ForecastTrader prediction markets (exchange FORECASTX) and standard options. Always use the secType, exchange, and months returned by search_contracts for subsequent calls — do not hardcode these values, as they vary by contract. Event contract prices represent probabilities (0.00–1.00) with a max $1.00 payout.

Flex Queries (Requires IB_FLEX_TOKEN)

| Tool | Description | | ------------------- | -------------------------------------------------------------------- | | get_flex_query | Execute a Flex Query and retrieve statements (auto-saves for reuse) | | list_flex_queries | List all previously used Flex Queries | | forget_flex_query | Remove a saved Flex Query from memory |

Troubleshooting

Authentication Problems:

• Use the web interface that opens automatically
• Complete any required two-factor authentication
• Try paper trading mode if live trading fails

Support

• This Server: Open an issue in this repository.

License

MIT License - see LICENSE file for details.