IBKR TWS MCP Server

# Implementation Status Summary ## Fixed Issues ### 1. Import Error - Optional Type **Status:** ✅ FIXED - **Issue:** `NameError: name 'Optional' is not defined` in `src/server.py` line 202 - **Solution:** Added `Optional` to the imports from `typing` module ### 2. MCP Server Endpoint Configuration **Status:** ✅ FIXED - **Issue:** 404 errors on `/api/v1/` and `/api/v1/manifest` endpoints - **Root Cause:** FastMCP's `streamable_http_app()` requires proper async initialization - **Solution:** Changed to use `mcp.sse_app()` which exposes SSE endpoints at `/api/v1/sse` and `/api/v1/messages` ### 3. Launch Configuration **Status:** ✅ FIXED - **Issue:** `.vscode/launch.json` needed proper configuration for `uv run python main.py` - **Solution:** Updated launch.json to use debugpy with correct Python debugging configuration ### 4. Documentation **Status:** ✅ ADDED - **Addition:** Comprehensive section in SETUP.md for connecting from Claude MCP Inspector - **Includes:** Step-by-step guide, troubleshooting, and tips for using the Inspector ## Current Server Endpoints The MCP server now exposes the following endpoints: ``` http://localhost:8000/api/v1/sse - SSE endpoint for MCP protocol communication http://localhost:8000/api/v1/messages - Messages endpoint for MCP protocol ``` ## MCP Tools Available All tools are implemented and accessible via the MCP protocol: ### Connection Management - `ibkr_connect` - Connect to TWS/IB Gateway - `ibkr_disconnect` - Disconnect from TWS - `ibkr_get_status` - Get connection status ### Contract and Market Data - `ibkr_get_contract_details` - Get contract details - `ibkr_get_historical_data` - Get historical market data - `ibkr_stream_market_data` - Stream real-time market data (SSE) ### Account and Portfolio - `ibkr_get_account_summary` - Get account summary - `ibkr_get_positions` - Get current positions - `ibkr_stream_account_updates` - Stream account updates (SSE) - `ibkr_get_pnl` - Get P&L - `ibkr_get_pnl_single` - Get single position P&L ### Order Management - `ibkr_place_order` - Place an order - `ibkr_cancel_order` - Cancel an order - `ibkr_get_open_orders` - Get open orders - `ibkr_get_executions` - Get executions ## How to Test ### 1. Start the Server ```bash cd /home/zhaoli/dev/git/ibkr-tws-mcp-server uv run python main.py ``` ### 2. Verify Server is Running ```bash # Check if SSE endpoint is accessible (will hang - that's expected for SSE) curl http://localhost:8000/api/v1/sse ``` ### 3. Connect via Claude MCP Inspector 1. Expose your local server using ngrok: ```bash ngrok http 8000 ``` 2. Open https://www.claudemcp.com/inspector 3. Enter the SSE endpoint URL: ``` https://your-ngrok-url.ngrok-free.app/api/v1/sse ``` 4. Test the tools through the Inspector UI ### 4. Run Unit Tests ```bash uv run pytest tests/unit/ -v ``` ### 5. Run Integration Tests (requires TWS running) ```bash uv run pytest tests/integration/ -v ``` ## Known Limitations 1. **HTTP Manifest Endpoint:** The current implementation uses SSE transport which doesn't expose a traditional `/manifest` endpoint. This is by design - MCP clients discover tools through the MCP protocol handshake over SSE. 2. **Direct HTTP Tool Invocation:** Tools cannot be invoked directly via HTTP POST to individual endpoints (e.g., `/api/v1/ibkr_connect`). All communication must go through the MCP protocol over the SSE connection. 3. **cURL Testing:** The `scripts/test_curl.sh` script needs to be updated to work with the SSE protocol instead of direct HTTP calls to individual tool endpoints. ## Next Steps (Optional Enhancements) 1. **Update test_curl.sh:** Modify the cURL test script to use SSE protocol or create MCP client examples 2. **Add REST API Wrapper:** If direct HTTP access to tools is needed, consider adding a REST API wrapper layer on top of the MCP server 3. **Enhanced Error Handling:** Add more detailed error responses and logging for easier debugging 4. **Metrics and Monitoring:** Add endpoint for health checks and metrics 5. **WebSocket Support:** Consider adding WebSocket transport in addition to SSE for better bi-directional communication ## Architecture Notes The server follows the MCP specification: - Uses Server-Sent Events (SSE) for client-server communication - Tools are invoked through MCP protocol messages, not direct HTTP calls - Supports streaming responses for real-time data (market data, account updates) - Implements proper lifespan management for the TWS client connection