fintools-ai/mcp-options-order-flow-server

MCP Options Order Flow Server

A high-performance Model Context Protocol (MCP) server for comprehensive options order flow analysis. This server provides real-time options order flow data, pattern detection, and institutional bias analysis through an intuitive MCP interface.

🚀 Features

• Real-time Options Flow Analysis: Monitor options order flow across multiple contracts with sub-10ms response times
• Advanced Pattern Detection: Identify sweeps, blocks, and unusual volume patterns with institutional-grade algorithms
• Institutional Bias Tracking: Monitor smart money positioning and directional sentiment
• Historical Trend Analysis: 30-minute interval analysis with key directional changes
• Dynamic Monitoring: Configure and monitor specific strike ranges and expirations without restarts
• High Performance: Built for production use with distributed Go+Python architecture

🏗️ Architecture

This MCP server integrates with the mcp-trading-data-broker Go service to provide:

┌─────────────────────┐    gRPC     ┌─────────────────────┐    WebSocket    ┌─────────────────────┐
│ MCP Options Server  │ ──────────► │ mcp-trading-data-   │ ──────────────► │ Market Data         │
│ (Python)            │             │ broker (Go)         │                 │ Provider            │
│                     │             │                     │                 │                     │
│ • MCP Tools         │             │ • Options Analysis  │                 │ • Options Quotes    │
│ • XML Formatting    │             │ • Pattern Detection │                 │ • Real-time Data    │
│ • Context Building  │             │ • Data Storage      │                 │                     │
└─────────────────────┘             └─────────────────────┘                 └─────────────────────┘

📋 Prerequisites

1. mcp-trading-data-broker: The Go-based data broker service

   • Provides gRPC server on port 9090
   • Handles real-time options data collection and analysis
   • Must be running before starting this MCP server

2. Python 3.8+: Required for MCP server

3. Network Access: For gRPC communication between services

⚡ Quick Start

1. Installation

# Clone the repository
git clone <repository-url>
cd mcp-options-order-flow-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On macOS/Linux
# venv\Scripts\activate     # On Windows

# Install dependencies
pip install -r requirements.txt

2. Configuration

Set environment variables:

# gRPC Data Broker Connection
export GRPC_HOST=localhost
export GRPC_PORT=9090
export GRPC_TIMEOUT=30

# Optional: Custom logging
export LOG_LEVEL=INFO

3. Start the Server

# Method 1: Using the convenience script
python run_server.py

# Method 2: Using module execution 
python -m src.mcp_server

# Method 3: Direct execution
python src/mcp_server.py

4. Claude Desktop Integration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "options-flow": {
      "command": "python",
      "args": ["run_server.py"],
      "cwd": "/path/to/mcp-options-order-flow-server",
      "env": {
        "GRPC_HOST": "localhost",
        "GRPC_PORT": "9090"
      }
    }
  }
}

🛠️ Available MCP Tools

1. analyze_options_flow

Get comprehensive options order flow analysis for a ticker.

Parameters:

• ticker (string): Stock ticker symbol (e.g., "SPY", "QQQ")

Returns: XML-formatted analysis including:

• Monitored contracts grouped by expiration and strike
• Current activity levels and directional bias
• Detected patterns with confidence scores
• Historical trend analysis with 30-minute intervals
• Institutional bias and most active strikes

2. configure_options_monitoring_tool

Configure options monitoring for specific contracts.

Parameters:

• ticker (string): Stock ticker symbol
• configurations (array): Configuration objects with:
  • expiration (integer): Expiration date in YYYYMMDD format
  • strike_range (array): List of strike prices to monitor
  • include_both_types (boolean): Monitor both calls and puts

Example:

{
  "ticker": "SPY",
  "configurations": [
    {
      "expiration": 20240419,
      "strike_range": [400, 405, 410],
      "include_both_types": true
    }
  ]
}

3. get_monitoring_status_tool

Get current monitoring configuration status.

Parameters:

• ticker (string): Stock ticker symbol

Returns: XML-formatted status showing all actively monitored contracts

4. data_broker_health_check

Check connectivity and health status of the data broker.

Returns: Health status with connection details and response time metrics

💡 Example Usage

1. Configure Monitoring

"Please monitor SPY options for expiration 2024-04-19, strikes 400-410, both calls and puts"

2. Analyze Options Flow

"Analyze the current options flow for SPY"

3. Check Monitoring Status

"What options contracts are currently being monitored for SPY?"

sites are properly configured