# MCP Options Order Flow Server
[](https://python.org)
[](https://modelcontextprotocol.io)
[](https://github.com/jlowin/fastmcp)
[](https://grpc.io)
[](https://opensource.org/licenses/MIT)
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
```bash
# 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:
```bash
# 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
```bash
# 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:
```json
{
"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:**
```json
{
"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
