Skip to main content
Glama

IBKR TWS MCP Server

by haymant
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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 HTTP Streaming for MCP protocol and WebSocket streaming for real-time data subscriptions (market data, portfolio updates, news bulletins).

Features

  • MCP Compliance: Built with FastMCP for full adherence to the Model Context Protocol with HTTP streaming support.

  • Asynchronous TWS Integration: Leverages ib_async (maintained fork of ib-insync) for non-blocking, asynchronous interaction with the TWS API.

  • Comprehensive Toolset: 51+ tools for connection management, market data retrieval (historical and streaming), account and portfolio querying, and order management (placing and canceling orders).

  • MCP Prompts: 6 guided workflows that combine multiple tools into expert-level trading strategies (bracket orders, portfolio rebalancing, risk assessment, options strategies, market analysis, and workspace setup).

  • Real-time WebSocket Streaming: Three dedicated WebSocket endpoints for continuous real-time data:

    • Market Data Stream - Real-time quotes for multiple symbols

    • Portfolio Stream - Live portfolio and account updates

    • News Stream - IBKR news bulletins and system messages

  • HTTP Streaming Transport: Uses chunked transfer encoding for efficient MCP tool responses.

  • CORS Support: Configured to allow cross-origin requests from browser-based MCP clients (e.g., Goflow, web applications).

  • Containerized Deployment: Ready-to-use Docker and Docker Compose configuration.

Architecture

┌─────────────────────────────────────────────────┐ │ Client Application │ ├─────────────────────────────────────────────────┤ │ 1. MCP Client (HTTP Streaming) │ │ POST /api/v1/mcp │ │ - Tool calls: connect, orders, positions │ │ │ │ 2. WebSocket Clients (real-time streams) │ │ WS /api/v1/stream/market-data │ │ WS /api/v1/stream/portfolio │ │ WS /api/v1/stream/news │ └─────────────────────────────────────────────────┘ │ │ │ HTTP POST │ WebSocket ▼ ▼ ┌─────────────────────────────────────────────────┐ │ IBKR TWS MCP Server │ ├─────────────────────────────────────────────────┤ │ • FastMCP Server (HTTP streaming) │ │ • WebSocket Handlers (real-time streaming) │ │ • Shared TWS Client (ib_async) │ └─────────────────────────────────────────────────┘ │ │ IB Client Protocol ▼ ┌─────────────────────────────────────────────────┐ │ TWS / IB Gateway │ │ (127.0.0.1:7497 or :4001) │ └─────────────────────────────────────────────────┘

Quick Start

1. Install Dependencies

# Using uv (recommended) uv sync # Or using pip pip install -r requirements.txt

2. Configure Environment

# Copy example environment file cp .env.example .env # Edit .env with your settings TWS_HOST=127.0.0.1 TWS_PORT=7497 TWS_CLIENT_ID=1 TWS_PAPER_ACCOUNT=DU2515295 SERVER_HOST=0.0.0.0 SERVER_PORT=8000

3. CORS Configuration (Browser Clients)

The server is configured to allow cross-origin requests from browser-based MCP clients:

  • Allowed Origins: All origins (*) - supports external domains like https://test.lizhao.net

  • Allowed Methods: GET, POST, PUT, DELETE, OPTIONS, HEAD

  • Allowed Headers: All headers including MCP-specific headers (Mcp-Session-Id, Mcp-Initialize-Request)

  • Credentials: Enabled for authenticated requests

  • Preflight Cache: 24 hours

This enables integration with browser-based MCP clients like Goflow without CORS restrictions.

4. Start TWS/Gateway

Launch Interactive Brokers TWS or IB Gateway and enable API connections.

5. Run the Server

uv run python main.py

5. Test the Server

# Health check curl http://localhost:8000/health # MCP tool call (connect to TWS) curl -X POST http://localhost:8000/api/v1/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "ibkr_connect", "arguments": {"host": "127.0.0.1", "port": 7497, "clientId": 1} }, "id": 1 }'

WebSocket Streaming Examples

Market Data Stream (Python)

import websockets import json import asyncio async def stream_quotes(): async with websockets.connect('ws://localhost:8000/api/v1/stream/market-data') as ws: # Subscribe to AAPL await ws.send(json.dumps({ "action": "subscribe", "symbol": "AAPL", "secType": "STK", "exchange": "SMART", "currency": "USD" })) # Receive real-time updates async for message in ws: data = json.loads(message) if data["type"] == "market_data": print(f"{data['symbol']}: ${data['data']['last']}") asyncio.run(stream_quotes())

Market Data Stream (JavaScript/Browser)

const ws = new WebSocket('ws://localhost:8000/api/v1/stream/market-data'); ws.onopen = () => { ws.send(JSON.stringify({ action: 'subscribe', symbol: 'AAPL', secType: 'STK' })); }; ws.onmessage = (event) => { const data = JSON.parse(event.data); if (data.type === 'market_data') { console.log(`${data.symbol}: $${data.data.last}`); } };

For complete examples including portfolio streams and news bulletins, see HTTP Streaming Examples.

MCP Prompts

The server includes 6 comprehensive prompts that provide guided workflows for complex trading operations:

Portfolio Management

  • setup_trading_workspace - Complete workspace setup with streaming resources

  • rebalance_portfolio - Portfolio rebalancing with tax optimization and OCA groups

  • assess_portfolio_risk - Risk analysis with beta weighting, VaR, and stress testing

Trading Execution

  • execute_bracket_order - Bracket orders with take-profit and stop-loss automation

  • execute_options_strategy - Options strategies (covered calls, protective puts, collars, etc.)

Market Analysis

  • analyze_market_conditions - Multi-dimensional analysis combining technicals, fundamentals, news, and options

Each prompt provides step-by-step workflows with tool call examples, best practices, risk warnings, and sample calculations. See Prompts Guide for details.

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.

Streaming Documentation

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 │ └── streaming/ # WebSocket streaming handlers │ ├── websocket_manager.py │ ├── market_data.py │ ├── portfolio.py │ └── news.py ├── 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 │ ├── HTTP_STREAMING_MIGRATION.md # Streaming migration plan │ ├── HTTP_STREAMING_EXAMPLES.md # Streaming examples │ ├── HTTP_STREAMING_SUMMARY.md # Streaming summary │ └── ... # 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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/haymant/tws-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server