Claude TWS Connect MCP Server

claude-tws-connect

MCP (Model Context Protocol) server that connects Claude to Interactive Brokers TWS via ib_insync. Use natural language to check your portfolio, pull market data, and place orders — all from Claude Desktop, Claude Code, or any MCP-compatible client.

Quick Start

macOS:

git clone https://github.com/danielkristofik/mcp_claude_ibkr.git
cd mcp_claude_ibkr
./install.sh

Linux (Ubuntu/Debian):

git clone https://github.com/danielkristofik/mcp_claude_ibkr.git
cd mcp_claude_ibkr
./install-linux.sh

The installer will:

1. Find or install Python 3.10+
2. Create a virtual environment and install dependencies
3. Let you choose Paper or Live trading port
4. Configure Claude Desktop automatically
5. Configure Claude Code (CLI) if installed

Features

Order Safety

Orders use a two-step confirmation flow:

1. ib_prepare_order — validates the contract, builds the order, and returns a confirmation token
2. Claude shows the order details to you and waits for explicit approval
3. ib_submit_order — submits the order only after confirmation (token expires in 5 minutes)

Manual Installation

Prerequisites

• Python 3.10+
• TWS or IB Gateway running and logged in
• TWS API enabled (Edit → Global Configuration → API → Settings)

Setup

git clone https://github.com/danielkristofik/mcp_claude_ibkr.git
cd mcp_claude_ibkr

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add the IBKR server:

{
  "mcpServers": {
    "ibkr": {
      "command": "/FULL/PATH/TO/claude-tws-connect/venv/bin/python",
      "args": ["/FULL/PATH/TO/claude-tws-connect/ibkr_mcp.py"]
    }
  }
}

Important: Use the full absolute path to the Python binary inside the venv.

See `claude_desktop_config_example.json` for a complete example.

Claude Code (CLI) Setup

If you use Claude Code, the MCP server can be configured with a single command:

claude mcp add --transport stdio --scope user ibkr -- /FULL/PATH/TO/claude-tws-connect/venv/bin/python /FULL/PATH/TO/claude-tws-connect/ibkr_mcp.py

Alternatively, this repository includes a .mcp.json file that makes the MCP server available automatically when you open the project directory in Claude Code — no manual configuration needed.

Verify

Restart Claude Desktop. The ib_* tools should appear in the tools list. Try:

"Show me my account summary"
"What positions do I have?"
"Get historical data for AAPL for the last month"

Configuration

Edit config.json or the variables at the top of ibkr_mcp.py:

TWS_HOST = "127.0.0.1"   # TWS host
TWS_PORT = 7496           # 7496 = live, 7497 = paper trading
CLIENT_ID = 10            # Unique client ID (avoid conflicts with other TWS connections)

TWS Setup

In TWS: Edit → Global Configuration → API → Settings:

• Enable ActiveX and Socket Clients
• Socket port: 7496 (live) or 7497 (paper)
• Uncheck "Read-Only API" if you want to place orders
• Add 127.0.0.1 to Trusted IPs

Remote IB Gateway

To connect to a remote IB Gateway, use an SSH tunnel:

ssh -L 4002:127.0.0.1:4002 user@remote-server

Then change TWS_PORT t