ibkr

This MCP server provides a FastAPI-based interface for Interactive Brokers (IBKR) trading operations and automatically manages an IBKR Gateway container when enabled. It exposes a REST API for common IBKR actions (positions, contract details, options chains, market data tickers, filtered options, and scanner results) in addition to an MCP endpoint at /mcp for model-context driven interactions. You can monitor gateway health via the gateway endpoints and optionally manage the gateway container lifecycle.

To start using it, run the server (as described in installation steps) and access the API docs at http://localhost:8000/docs. The MCP endpoints are available at http://localhost:8000/mcp. You can retrieve current positions, contract details, and market data through the IBKR-related routes, or use the MCP interface to integrate with other models or services that rely on MCP for context-aware trading actions.

Prerequisites:

• Python 3.8+ (recommended 3.10+)
• Knowledge of IBKR Gateway access credentials
• Git (optional for cloning)

Installation steps:

1. Clone the repository

git clone <repository-url>
cd ibkr-mcp-server

2. Create a virtual environment (optional but recommended)

python -m venv venv
source venv/bin/activate  # on macOS/Linux
venv\Scripts\activate     # on Windows

3. Install dependencies (the project documents using uv for setup)

uv sync

4. Prepare environment variables (examples shown; replace with real credentials)

export IBKR_IB_GATEWAY_USERNAME="YOUR USERNAME"
export IBKR_IB_GATEWAY_PASSWORD="YOUR PASSWORD"
export PORT=8000

5. Run the server

python main.py --ib-gateway-username=$IBKR_IB_GATEWAY_USERNAME --ib-gateway-password=$IBKR_IB_GATEWAY_PASSWORD

6. Verify the server is running at http://localhost:8000 and the MCP endpoint at http://localhost:8000/mcp

Optional: If you intend to run via Docker or Helm as described in the README, follow those deployment paths and ensure the same environment variables are provided to the container or Helm values.

Notes and tips:

• If you encounter port conflicts, ensure port 8000 is free or override PORT environment variable.
• When using the IBKR Gateway via Docker, make sure Docker is running and the gateway container can access IBKR services.
• The MCP endpoint at /mcp enables model-context protocol interactions; ensure clients sending MCP requests use the correct base URL.
• If you modify gateway management behavior, review the health checks and restart policies to avoid unnecessary restarts.
• For troubleshooting, verify credentials and IBKR gateway configuration, and check logs available from the gateway endpoints if the /gateway/status or /gateway/logs endpoints are enabled.