This MCP server provides a comprehensive integration with Interactive Brokers (IBKR) API, exposing a suite of tools to Claude Desktop and Claude Code for portfolio management, market data, and trading operations. It supports multi-account management, real-time quotes, historical data, short selling analysis, borrow rates, margin requirements, and automated trading actions with safety checks. The server exposes a variety of tools such as get_portfolio, get_account_summary, switch_account, get_market_data, get_historical_data, place_order, and get_margin_requirements, allowing you to query, analyze, and trade across multiple IBKR accounts. Claude can be configured to connect to this MCP server using the provided Python entry point, enabling conversational access to IBKR data and trading actions through natural language prompts.

To use these capabilities, start the MCP server with the Python module entry point and ensure your Claude integration is configured as shown in the Claude Integration section of the README. Once running, you can issue natural language requests like: retrieve your current portfolio, switch to a specific IBKR account, request real-time quotes for a set of symbols, or place a limit order with appropriate safety checks. The toolset is designed to be robust for paper trading and offers safety features to prevent unintended live trading unless explicitly enabled in configuration.

Prerequisites:

• Python 3.10 or higher
• Access to an IBKR account with TWS or IB Gateway
• Claude Desktop or Claude Code (for MCP integration)

Installation steps:

1. Clone the repository: git clone https://github.com/yourusername/ibkr-mcp-server.git cd ibkr-mcp-server

2. Set up a Python virtual environment (recommended): python -m venv venv

   Windows

   venv\Scripts\activate.bat

   macOS/Linux

   source venv/bin/activate

3. Install the package and development dependencies: pip install -e ".[dev]" # or use a regular install if not developing

   Optional: install test dependencies

   pip install -r requirements-dev.txt

4. Prepare environment variables (examples):

   Copy the example env and customize

   cp .env.example .env

   Edit .env with your IBKR settings

5. Run the server for testing: python -m ibkr_mcp_server.main --test

6. (Optional) Run unit tests: pytest tests/ -v

7. If you plan to deploy in production, configure appropriate service management and environment variables as described in the Deployment/Configuration sections of the README.

Tips and common issues:

• Ensure IBKR API is enabled in TWS/IB Gateway settings and that your IP is trusted.
• Use paper trading mode (IBKR_IS_PAPER=true) during testing to avoid real trades.
• If you change environment variables, restart the MCP server for changes to take effect.
• For Claude integration, ensure the cwd paths in the Claude config point to your local ibkr-mcp-server directory.
• When testing connectivity, validate get_connection_status and ensure API permissions are correct in your IBKR account.
• If you encounter port conflicts, adjust IBKR_PORT or the service binding as needed.
• Keep dependencies up to date and run code quality tools (black, isort, mypy) as part of development.