SumpPump by Schmoll86 - MCP Server

SumpPump - IBKR Trading Assistant

Production-ready MCP (Model Context Protocol) server that bridges Claude Desktop with Interactive Brokers TWS for conversational options trading and market analysis. All 47 trading tools are fully integrated and operational with V2 architecture, including portfolio management and live data streaming.

✅ Current Status (v2.1.2 - August 2025)

47 MCP Tools: All tools properly registered and functional
Refactored Architecture: Modular tool organization with BaseTool class
Live Trading: Production-ready with real money trading
TWS Integration: Complete with auto-reconnection and lazy loading
Risk Management: Mandatory confirmation workflows
Level 2 Options: Full support for IBKR Level 2 strategies
Session State: Strategy persistence with 5-minute TTL
Greeks Data: Full options Greeks with retry mechanism
Performance: 15% code reduction, standardized error handling
Tool Composition: Internal implementation pattern enables tool-to-tool calls
Execution Reliability: Fixed critical bugs in order execution (trailing stops, type conversion)
Market Awareness: Validates market hours before placing options orders

Features

Core Trading Capabilities

Options Trading: Full options chain access with Greeks, multi-leg strategies
Real-Time Market Data: Live quotes, Level 1/2 data, options chains
Strategy Analysis: Calculate P&L, breakeven points, and risk metrics
Trade Execution: Place orders with mandatory confirmation workflow
Risk Management: Position sizing, stop-loss prompts, max loss calculations

Working MCP Tools (47 Total)

Market Data (12 tools)

trade_get_quote - Real-time stock/ETF quotes
trade_get_options_chain - Full options chain with Greeks
trade_get_price_history - Historical OHLCV data
trade_get_positions - Current portfolio positions
trade_get_open_orders - Pending orders
trade_get_account_summary - Account balances and margin
trade_get_news - News feed (if subscribed)
trade_get_watchlist_quotes - Multiple symbol quotes
trade_get_market_depth - Level 2 order book
trade_get_depth_analytics - Price impact analysis
trade_scan_market - Scan for high IV, unusual options, momentum stocks
trade_check_market_data - Verify market data feed status

Strategy & Risk (8 tools)

trade_calculate_strategy - Analyze options strategies
trade_check_margin_risk - Margin call risk assessment
trade_get_volatility_analysis - IV rank and volatility metrics
trade_get_index_quote - Index quotes (SPX, NDX, VIX)
trade_get_index_options - Index options chains
trade_get_vix_term_structure - VIX term structure analysis
trade_analyze_opportunity - Comprehensive trade opportunity analysis
trade_get_session_status - Trading session state and workflow status

Execution (11 tools)

trade_execute - Execute trades with confirmation
trade_execute_with_verification - Execute with enhanced verification
trade_close_position - Close existing positions
trade_set_stop_loss - Set protective stops
trade_modify_order - Modify pending orders
trade_cancel_order - Cancel pending orders
trade_create_conditional_order - Create conditional/bracket orders
trade_buy_to_close - Buy to close options positions
trade_direct_close - Direct position closing without confirmation
trade_emergency_close - Emergency close all positions
trade_set_price_alert - Set price alerts

Extended Hours (3 tools)

trade_place_extended_order - Place extended hours orders
trade_get_extended_schedule - Get extended trading schedule
trade_modify_for_extended - Modify order for extended hours

Portfolio Management (4 tools) - NEW in v2.0.3

trade_get_portfolio_summary - Aggregate P&L and portfolio Greeks
trade_get_history - Query past trades with filters
trade_adjust_position - Smart position adjustments (roll/resize/hedge)
trade_analyze_greeks - Portfolio-wide Greeks analysis with scenarios

Event-Driven & Bracket Orders (4 tools) - NEW in v2.0.3

trade_start_live_updates - Stream real-time market data
trade_execute_bracket - Place bracket orders with profit/stop
trade_get_historical_executions - Get historical execution data
trade_get_live_status - Check live data streaming status

Advanced (5 tools)

trade_roll_option - Roll options forward
trade_get_crypto_quote - Crypto quotes (config required)
trade_analyze_crypto - Crypto analysis (config required)
trade_get_fx_quote - Forex quotes (config required)
trade_analyze_fx_pair - FX analysis (config required)

Quick Start

Prerequisites

Interactive Brokers TWS or IB Gateway running
Python 3.11+
Claude Desktop with MCP support
Active IBKR account with Level 2 options permissions

Installation

Clone the repository:

git clone https://github.com/yourusername/SumpPump.git
cd SumpPump

Run setup:

./setup.sh

Configure environment:

cp .env.example .env
# Edit .env with your settings

Configure Claude Desktop: Add to claude_desktop_config.json:

{
  "mcpServers": {
    "sump-pump": {
      "command": "/path/to/SumpPump/venv/bin/python",
      "args": ["/path/to/SumpPump/src/mcp/server.py"],
      "env": {}
    }
  }
}

Start TWS and Claude Desktop

Configuration

Essential Settings (.env)

# TWS Connection
TWS_HOST=127.0.0.1
TWS_PORT=7497  # 7497 for live, 7496 for paper
TWS_CLIENT_ID=5
TWS_ACCOUNT=  # Leave empty for auto-detect

# Market Data
USE_DELAYED_DATA=false
USE_LEVEL2_DEPTH=true
ENABLE_INDEX_TRADING=true
SUBSCRIBE_TO_NEWS=true

# Optional Features
USE_CRYPTO_FEED=false  # Enable for crypto
USE_FX_FEED=false      # Enable for forex

# Risk Management
REQUIRE_CONFIRMATION=true
MAX_POSITION_SIZE_PERCENT=5.0
DEFAULT_STOP_LOSS_PERCENT=10.0

Session Setup

IMPORTANT: Start each session by reading SESSION_PRIMER.md:

Read SESSION_PRIMER.md and use it as context for this session.

Then fill in the placeholders and proceed with trading.

Usage Examples

In Claude Desktop:

"Show me SPY options chain for next Friday"
"Calculate a bull call spread on AAPL 150/155"
"Get my current positions"
"What's my account balance and margin status?"
"Execute a long call on TSLA 250 strike"
"Show Level 2 depth for NVDA"
"Scan for bearish_tech opportunities"

Safety Features

Mandatory Confirmation: All trades require "USER_CONFIRMED" token
Max Loss Display: Always shows maximum potential loss before execution
Stop Loss Prompts: Automatic prompts after fills
Level 2 Only: No naked options or credit spreads without Level 3
Rate Limiting: Prevents API overload
Connection Monitoring: Auto-reconnection on disconnect

Project Structure

SumpPump/
├── src/
│   ├── mcp/
│   │   └── server.py          # MCP server with 47 tools
│   ├── core/                  # Infrastructure
│   │   ├── exceptions.py      # Error hierarchy
│   │   ├── connection_monitor.py
│   │   ├── rate_limiter.py
│   │   └── settings.py
│   ├── modules/
│   │   ├── tws/               # TWS connection
│   │   ├── data/              # Market data modules
│   │   ├── strategies/        # Level 2 strategies
│   │   ├── execution/         # Order execution
│   │   └── risk/              # Risk management
│   └── models.py              # Data models
├── tests/                     # Test suite
├── .env                       # Configuration
├── CLAUDE.md                  # Context for Claude
└── README.md                  # This file

Recent Updates (v2.0.3 - January 2025)

New Features

Portfolio Management: Complete portfolio analysis with P&L and Greeks aggregation
Event-Driven Updates: Live streaming market data with callbacks
Bracket Orders: Automatic profit target and stop loss orders
Position Adjustments: Roll, resize, hedge, and partial close capabilities

Previous Fixes (v2.0.2 - January 2025)

Event Loop Conflicts

Problem: "This event loop is already running" error
Solution: Applied nest_asyncio patch for nested event loop compatibility
Files: src/mcp/server.py, src/modules/tws/connection.py

Greeks Data Retrieval

Problem: Options Greeks showing as 0 or NaN
Solution: Added explicit Greeks request with genericTickList='106' and proper wait time
File: src/modules/tws/connection.py (lines 368-396)

Strategy Session State

Problem: Strategy lost between calculate and execute calls
Solution: Implemented SessionState class for strategy persistence
File: src/mcp/server.py (lines 44-79)

Async/Await Syntax Errors

Problem: 'await' outside async function in base strategy
Solution: Made _find_breakeven_in_range async
File: src/modules/strategies/base.py (line 394)

Troubleshooting

Connection Issues

Verify TWS is running and API is enabled
Check port settings (7497 for live)
Ensure Client ID is not in use (auto-finds available ID)
Check firewall settings
Account should show as U16348403 (or your account)

"FunctionTool not callable" in Claude Desktop

This is normal behavior for MCP tools. The tools work correctly through the MCP interface.

Market Data Issues

Verify market data subscriptions in IBKR
Check if market is open
Confirm symbol validity
Greeks require options data subscription

After Hours

Options will show NaN for bid/ask
Use limit orders with manual pricing
News feeds may be empty

Requirements

IBKR Account with Level 2 options permissions
Market data subscriptions (US equities/options minimum)
TWS API enabled on port 7497
Python packages: ib_async, fastmcp, pydantic, loguru

Support

Documentation: See CLAUDE.md for detailed context
TWS API Docs: IBKR API Documentation

License

MIT License - See LICENSE file for details

Disclaimer

IMPORTANT: This software executes real trades with real money. Trading involves substantial risk of loss. Always verify orders before execution. Test thoroughly in paper trading first. The authors are not responsible for any financial losses.