IBKR

This MCP server exposes Interactive Brokers data through the MCP interface. It can fetch your portfolio with positions and P&L, retrieve an account summary with balances and key metrics, look up real-time stock prices, and price options based on symbol, expiry, strike, and right. Typical interactions involve asking your AI assistant to fetch the latest portfolio, run a quick market check, or compare account metrics. The server is intended to be run locally with TWS/IB Gateway connected, and it uses the TWS API credentials configured in your environment. You can test connectivity with a small script that attempts to initialize the connection, then issue the get_* methods through the MCP-enabled interface. When running, the server listens for MCP queries and returns structured data that your AI assistant can reason about and present to users.

Prerequisites:

• A wired or paper Interactive Brokers account and a running TWS or IB Gateway instance
• Python 3.10+
• Network access toibo the IB API port (default 7497 for paper, 7496 for live)

Installation steps:

1. Clone the repository:

git clone https://github.com/your-username/IBKR-MCP-Server.git
cd IBKR-MCP-Server

2. Create and activate a virtual environment:

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

3. Install the package in editable mode (recommended):

pip install -e .

4. Ensure dependencies are installed (if not covered by the editable install):

pip install -r requirements.txt

5. Configure connection settings (see env.example):

cp env.example .env
# Edit .env to set IBKR_* values, e.g. IBKR_HOST, IBKR_PORT, IBKR_CLIENT_ID, IBKR_IS_PAPER

6. Run the MCP server (example using Python directly):

python src/ibkr_mcp/server.py

Optional (recommended): use UV/uvx for faster startup and environment isolation as shown in the quick start of the README:

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
uv run python src/ibkr_mcp/server.py

Tips and common issues:

• Ensure TWS/IB Gateway is running and API access is enabled in TWS settings. Disable Read-Only API to allow data access.
• Make sure the correct port is used: 7497 for paper trading, 7496 for live trading.
• If you modify environment variables (IBKR_HOST, IBKR_PORT, IBKR_CLIENT_ID, IBKR_IS_PAPER), restart the server to apply changes.
• When integrating with Claude or other tools, provide the correct working directory and the same environment variables in your config.
• If the connection fails, check firewall rules and local network access to the IB API port and confirm TWS/IB Gateway is not blocking the connection.
• For debugging, log detailed connection errors from the server to identify whether the issue is authentication, port mismatch, or TWS configuration.