ibkr

This MCP server implements an Interactive Brokers (IBKR) MCP service built on FastMCP 2.0 and MCP StreamableHTTP. It exposes a set of 9 MCP tools for account management, trading operations, market data, and connection management, enabling clients to query account summaries, positions, and balances; place and cancel orders; fetch real-time and historical market data; and monitor connection status. The server runs as a Python module and can be integrated with Claude Desktop or other MCP clients via HTTP/WebSocket, using a simple JSON-encoded tool invocation pattern. Examples include placing a limit order for a stock, retrieving current positions, and requesting historical data for a contract. The server is designed with Pydantic-based data validation, asynchronous I/O for high performance, and configurable logging and environment-based configuration.

To get started, configure your environment variables for MCP (host and port) and IBKR (host, port, and client ID). Then start the server using the provided CLI: python -m ibkr_mcp_server.cli serve. Once running, you can send MCP tool requests to endpoints exposed by the server and receive structured JSON responses.

Prerequisites:

• Python 3.8+ and a virtual environment tool (venv or conda)
• Git to clone the repository (or access to the package source)

Installation steps:

1. Clone the repository

git clone https://github.com/yourusername/ibkr-mcp-server.git
cd ibkr-mcp-server

2. Create and activate a virtual environment

python3 -m venv venv
source venv/bin/activate

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

pip install -e .

4. Optional: install development dependencies

pip install -e ".[dev]"

5. Run pre-commit hooks (optional during development)

pre-commit install

6. Configure environment variables (see .env example in README) and start the server as described in the mcp_config section.

Notes and tips:

• Ensure IBKR TWS or IB Gateway is running and API access is enabled before starting the MCP server.
• Use distinct IBKR client IDs if you open multiple connections.
• The server supports environment-based configuration; you can place settings in a .env file or export variables in your shell.
• For production, enable DEBUG or set LOGGING__LEVEL to DEBUG temporarily when troubleshooting, then revert to INFO or WARN.
• If you encounter connection issues, verify the IBKR port and host values, and confirm that the API is enabled in IBKR's settings.
• This server framework follows a modular architecture; you can swap in alternative IBKR wrappers or data models with minimal changes.