Skip to main content
Glama

IBKR TWS MCP Server

by haymant
SETUP.md8.28 kB
# IBKR TWS MCP Server Setup Guide This guide provides instructions for setting up and running the IBKR TWS MCP Server for both local development and containerized deployment. ## 1. Prerequisites Before starting, ensure you have the following installed: * **Python 3.11+** * **uv** (recommended package installer and project manager) * **Docker** and **Docker Compose** (for containerized deployment) * **Interactive Brokers Trader Workstation (TWS)** or **IB Gateway** running and logged in. It is highly recommended to use a **Paper Trading** account for all testing. ## 2. Local Development Setup 1. **Clone the Repository and Navigate:** ```bash git clone <repository-url> cd ibkr-tws-mcp-server ``` 2. **Install Dependencies:** The project uses `uv` for dependency management. ```bash uv sync ``` 3. **Configure Environment Variables:** Create a `.env` file by copying the example and filling in your TWS connection details. ```bash cp .env.example .env # Edit the .env file with your TWS host and port ``` **Example `.env`:** ```bash # TWS/IB Gateway Connection TWS_HOST=127.0.0.1 TWS_PORT=7496 # 7496 for TWS, 4001 for IB Gateway Paper, 4002 for IB Gateway Live TWS_CLIENT_ID=1 # Server Configuration SERVER_HOST=0.0.0.0 SERVER_PORT=8000 API_PREFIX=/api/v1 ``` 4. **Run the Server:** The server is an ASGI application run with `uvicorn`. ```bash uv run python main.py # or uv run uvicorn src.server:app --host 0.0.0.0 --port 8000 ``` The server will be accessible at `http://localhost:8000/api/v1`. ## 3. Containerized Deployment with Docker 1. **Build the Docker Image:** Ensure your `.env` file is configured correctly. ```bash docker-compose build ``` 2. **Run the Container:** The `docker-compose.yml` file is configured to use `host.docker.internal` to connect to the TWS/IB Gateway running on your host machine. ```bash docker-compose up -d ``` 3. **Verify Deployment:** The server will be running on port `8000` of your host machine. ```bash curl http://localhost:8000/api/v1/manifest ``` You should receive the MCP server manifest JSON. ## 4. Testing The project includes unit and integration tests. 1. **Run Unit Tests:** ```bash uv run pytest tests/unit/ ``` 2. **Run Integration Tests:** **Note:** Integration tests require a running TWS/IB Gateway connected to a paper trading account. ```bash uv run pytest tests/integration/ ``` 3. **Run cURL Test Script:** This script provides a quick end-to-end check of the server's HTTP interface. ```bash ./scripts/test_curl.sh ``` ## 5. Connecting from Claude MCP Inspector The Claude MCP Inspector is a web-based tool for testing and interacting with MCP servers. You can use it to explore the available tools and test the server's functionality. ### Prerequisites * The IBKR TWS MCP server must be running (locally or in Docker) * For remote access, you'll need to expose your local server using a tunneling service like **ngrok** or **localtunnel** ### Step-by-Step Guide 1. **Start the MCP Server** Run the server locally: ```bash uv run python main.py ``` The server will start at `http://localhost:8000/api/v1`. 2. **Expose the Server (for Remote Access)** If you want to connect from the web-based Claude MCP Inspector, you need to expose your local server: **Using ngrok:** ```bash # Install ngrok from https://ngrok.com/download ngrok http 8000 ``` This will provide a public URL like: `https://xxxx-xxxx-xxxx.ngrok-free.app` **Using localtunnel:** ```bash # Install localtunnel npm install -g localtunnel # Expose port 8000 lt --port 8000 ``` This will provide a public URL like: `https://your-subdomain.loca.lt` 3. **Open the Claude MCP Inspector** Navigate to: **[https://www.claudemcp.com/inspector](https://www.claudemcp.com/inspector)** 4. **Configure the Server Connection** In the Inspector interface: * Locate the **"Server URL"** or **"Server Endpoint"** input field * Enter your server URL: * **For ngrok:** `https://xxxx-xxxx-xxxx.ngrok-free.app/api/v1/sse` * **For localtunnel:** `https://your-subdomain.loca.lt/api/v1/sse` * **For local (advanced):** `http://localhost:8000/api/v1/sse` * Click **"Connect"** 5. **Explore and Test Tools** Once connected, the Inspector will: * Display all available MCP tools in the sidebar * Show tool descriptions and parameters * Allow you to invoke tools with custom arguments * Display responses and streaming data 6. **Test the E2E Workflow** Try testing the portfolio rebalancing workflow: a. **Connect to TWS:** * Select the `ibkr_connect` tool * Enter TWS connection parameters (host, port, clientId) * Click "Invoke" b. **Get Market Data:** * Select `ibkr_get_historical_data` * Enter symbol (e.g., "VTI") * Click "Invoke" c. **Get Portfolio Data:** * Select `ibkr_get_positions` * Click "Invoke" * Select `ibkr_get_account_summary` * Click "Invoke" d. **Place Test Order:** * Select `ibkr_place_order` * Enter order details (symbol, action, quantity) * Click "Invoke" e. **Monitor Orders:** * Select `ibkr_get_open_orders` * Click "Invoke" ### Tips for Using the Inspector * **Streaming Tools:** Tools like `ibkr_stream_market_data` will show real-time updates in the Inspector's output panel ### Troubleshooting Inspector Connections * If the Inspector cannot fetch the manifest, try these quick checks: - Confirm the server is running: `uv run python main.py`. - Try fetching the manifest directly with curl (tries common paths): ```bash curl -sS http://localhost:8000/api/v1/mcp/manifest || curl -sS http://localhost:8000/api/v1/manifest || curl -sS http://localhost:8000/api/v1/sse ``` * If you see `Task group is not initialized` in server logs, restart the server and ensure you're starting it with the main entrypoint (`uv run python main.py`) so FastMCP can initialize its task groups. * If the Inspector shows tools but streaming tools are silent, make sure you first call `ibkr_connect` to establish a live TWS connection. * For remote Inspector sessions (Inspector not running on the same machine), use ngrok/localtunnel to expose your local server and provide the public URL to the Inspector. * **Error Messages:** Check the Inspector's console for detailed error messages if a tool fails * **Session Management:** The Inspector maintains session state, so you only need to connect to TWS once * **CORS Issues:** If you encounter CORS errors when connecting from the web-based Inspector, ensure the server has proper CORS configuration (already included in this implementation) ### Troubleshooting Inspector Connection | Issue | Solution | | :--- | :--- | | **Connection timeout** | Ensure the server is running and accessible at the specified URL. Check firewall settings. | | **CORS errors** | The server includes CORS middleware. If issues persist, check browser console for specific CORS policy violations. | | **ngrok/localtunnel errors** | Ensure the tunneling service is running and the URL is correct. Note that free ngrok URLs may have request limits. | | **404 errors** | Verify you're using the correct endpoint path: `/api/v1/sse` (not just `/api/v1`) | ## 6. Troubleshooting | Issue | Potential Cause | Solution | | :--- | :--- | :--- | | `ConnectionRefusedError` | TWS/IB Gateway is not running, or the port is incorrect. | Ensure TWS/IB Gateway is running and logged in. Verify `TWS_PORT` in `.env` is correct (e.g., 7496, 4001). | | `ib_async` timeout | TWS/IB Gateway is running but the connection is blocked. | Check firewall settings. Ensure the host and client ID are correct. | | Docker connection issue | `host.docker.internal` not resolving. | Ensure your Docker version supports `host-gateway`. Try replacing `host.docker.internal` with your host machine's IP address in the `.env` file. |

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