# 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

```bash
# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt
```

### 2. Configure Environment

```bash
# 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

```bash
uv run python main.py
```

### 5. Test the Server

```bash
# 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)

```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)

```javascript
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](./docs/HTTP_STREAMING_EXAMPLES.md).

## 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](./docs/PROMPTS_GUIDE.md) for details.

## Getting Started

Please refer to the [Setup Guide](./docs/SETUP.md) 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](./docs/API.md).

## Streaming Documentation

- **[HTTP Streaming Migration](./docs/HTTP_STREAMING_MIGRATION.md)** - Migration plan and architecture
- **[HTTP Streaming Examples](./docs/HTTP_STREAMING_EXAMPLES.md)** - Complete client examples
- **[HTTP Streaming Summary](./docs/HTTP_STREAMING_SUMMARY.md)** - Changes and best practices

## 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](./docs/API.md#2-end-to-end-testing-with-claude-mcp-inspector) 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](./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

- **[Setup Guide](./docs/SETUP.md)** - Installation and configuration
- **[API Reference](./docs/API.md)** - Complete tool documentation
- **[Prompts Guide](./docs/PROMPTS_GUIDE.md)** - MCP prompts quick reference
- **[Design Document](./docs/Design.md)** - Architecture and design decisions
- **[HTTP Streaming Guide](./docs/HTTP_STREAMING_MIGRATION.md)** - Real-time streaming architecture
- **[Streaming Examples](./docs/HTTP_STREAMING_EXAMPLES.md)** - Client code examples
- **[Project Structure](./PROJECT_STRUCTURE.md)** - Detailed project organization
- **[Migration Guide](./docs/MIGRATION_TO_IB_ASYNC.md)** - ib-insync to ib_async migration