IBKR TWS MCP Server

This project implements a Model Context Protocol (MCP) server for the Interactive Brokers (IBKR) Trader Workstation (TWS) API. It uses the official modelcontextprotocol/python-sdk and ib_async to expose key TWS functionalities as MCP tools, enabling seamless integration with LLM clients for automated financial workflows, such as portfolio rebalancing.

The server supports the Streamable HTTP transport and is designed to be easily containerized using Docker.

Features

• MCP Compliance: Built with FastMCP for full adherence to the Model Context Protocol.
• Asynchronous TWS Integration: Leverages ib_async (maintained fork of ib-insync) for non-blocking, asynchronous interaction with the TWS API.
• Comprehensive Toolset: Exposes tools for connection management, market data retrieval (historical and streaming), account and portfolio querying, and order management (placing and canceling orders).
• Streaming Support: Implements Server-Sent Events (SSE) for real-time market data and account updates.
• Containerized Deployment: Ready-to-use Docker and Docker Compose configuration.

Getting Started

Please refer to the Setup Guide for detailed instructions on prerequisites, environment configuration, and running the server locally or in a container.

API Reference

A complete list of all exposed MCP tools, their parameters, and return types can be found in the API Reference.

End-to-End Testing

The server is designed to support the portfolio rebalancing E2E case. You can test all functionalities using the Claude MCP Inspector.

See the dedicated section in the API Reference for a step-by-step guide on how to use the Inspector to interact with your running server.

Project Structure

For a detailed explanation of the project organization, see PROJECT_STRUCTURE.md.

ibkr-tws-mcp-server/
├── src/                   # Source code
│   ├── server.py          # FastMCP server and tool definitions
│   ├── tws_client.py      # TWS client wrapper using ib_async
│   └── models.py          # Pydantic data models
├── tests/                 # Test suite
│   ├── unit/              # Unit tests with mocks
│   └── integration/       # Integration test documentation
├── docs/                  # Documentation
│   ├── API.md             # MCP tools API reference
│   ├── SETUP.md           # Setup and deployment guide
│   └── ...                # Additional guides and troubleshooting
├── diagnostics/           # Diagnostic and testing scripts
├── scripts/               # Utility scripts
├── main.py                # Application entry point
├── pyproject.toml         # Project dependencies
└── README.md              # This file

Documentation

• Setup Guide - Installation and configuration
• API Reference - Complete tool documentation
• Design Document - Architecture and design decisions
• Project Structure - Detailed project organization
• Migration Guide - ib-insync to ib_async migration