Unusual Whales MCP Server

An MCP server that provides access to Unusual Whales market data - options flow, dark pool activity, congressional trades, and more. Works with any MCP-compatible client (Claude, or any LLM/application that supports MCP).

What You Can Do

Ask about the market using natural language:

"What's the options flow for AAPL today?"
"Show me the latest congressional trades"
"What's the dark pool activity for TSLA?"
"Get the max pain for SPY options expiring this Friday"
"What are institutions buying in the tech sector?"
"Give me a daily market summary"
"Deep dive on NVDA - options, dark pool, insider activity"

Available Data

| Category | What's Included | |----------|-----------------| | Stock | Options chains, Greeks, IV rank, OHLC candles, max pain, open interest, volatility | | Options | Contract flow, historic prices, intraday data, volume profiles | | Flow | Options flow alerts, full tape, net flow by expiry, sector flow (mag7, semis, etc.) | | Dark Pool | Dark pool transactions with filtering | | Congress | Congressional trades, late reports, individual member activity | | Politicians | Portfolios, recent trades, holdings by ticker | | Insider | Insider transactions, sector flow, ticker flow | | Institutions | 13F filings, holdings, sector exposure, ownership | | Market | Market tide, sector tide, economic calendar, FDA calendar, correlations | | Earnings | Premarket and afterhours schedules, historical earnings | | ETF | Holdings, exposure, inflows/outflows, sector weights | | Shorts | Short interest, FTDs, short volume ratio | | Seasonality | Market seasonality, monthly performers, ticker patterns | | Screener | Stock screener, options screener, analyst ratings | | News | Market news headlines |

Built-in Analysis Prompts

The server includes many ready-to-use prompts. Just ask to use any prompt by name.

Market Overview

| Prompt | Description | Example | |--------|-------------|---------| | daily-summary | Comprehensive market overview with tide, sectors, flow, dark pool | "Use the daily-summary prompt" | | morning-briefing | Start the day with tide, earnings, and key activity | "Use the morning-briefing prompt" | | end-of-day-recap | EOD summary with top movers, sectors, and themes | "Use end-of-day-recap" | | weekly-expiration | Max pain, gamma, and OI for weekly expiration | "Use weekly-expiration for SPY, QQQ, IWM" | | top-movers | Top tickers by net premium and options impact | "Use top-movers" |

Ticker Analysis

| Prompt | Description | Example | |--------|-------------|---------| | ticker-analysis | Deep dive on a stock with options, dark pool, insiders, catalysts | "Use ticker-analysis for NVDA" | | options-setup | IV rank, term structure, max pain - is premium cheap or expensive? | "Use options-setup for TSLA" | | pre-earnings | Historical moves, IV, positioning before earnings | "Use pre-earnings for AAPL" | | greek-exposure | Gamma, delta, vanna exposure by strike | "Use greek-exposure for SPY" | | short-interest | Short interest, FTDs, squeeze potential | "Use short-interest for GME" | | option-contract | Deep dive on a specific option contract | "Use option-contract for AAPL240119C00150000" | | correlation-analysis | Analyze correlations between tickers | "Use correlation-analysis for NVDA,AMD,INTC" |

Flow & Activity

| Prompt | Description | Example | |--------|-------------|---------| | unusual-flow | Scan for unusual options activity across the market | "Use unusual-flow with min_premium 500000" | | dark-pool-scanner | Find large dark pool prints and institutional activity | "Use dark-pool-scanner" | | sector-flow | Options flow sentiment for sector groups (mag7, semi, bank, etc.) | "Use sector-flow for semi" |

Smart Money

| Prompt | Description | Example | |--------|-------------|---------| | congress-tracker | Recent congressional trading with pattern detection | "Use congress-tracker" | | politician-portfolio | Portfolio holdings and trades for a specific politician | "Use politician-portfolio for Nancy Pelosi" | | insider-scanner | Scan for insider buying/selling patterns | "Use insider-scanner" | | institutional-activity | 13F filings, holdings changes, sector rotation | "Use institutional-activity for technology" | | analyst-tracker | Analyst ratings with options flow correlation | "Use analyst-tracker" |

Calendars & Events

| Prompt | Description | Example | |--------|-------------|---------| | earnings-calendar | Earnings with IV, expected moves, and positioning | "Use earnings-calendar for this week" | | fda-calendar | FDA events with biotech options activity | "Use fda-calendar" | | economic-calendar | FOMC, CPI, jobs data with market positioning | "Use economic-calendar" |

Screening & Discovery

| Prompt | Description | Example | |--------|-------------|---------| | iv-screener | Find high or low IV rank stocks for options strategies | "Use iv-screener" | | bullish-confluence | Stocks with bullish flow + dark pool + insider buying | "Use bullish-confluence" | | bearish-confluence | Stocks with bearish flow + distribution + insider selling | "Use bearish-confluence" | | news-scanner | Market news headlines with related flow | "Use news-scanner" or "Use news-scanner for TSLA" |

Other

| Prompt | Description | Example | |--------|-------------|---------| | seasonality | Historical seasonal patterns for a ticker or market | "Use seasonality for AAPL" | | etf-flow | ETF inflows/outflows or find ETF exposure for a stock | "Use etf-flow for QQQ" |

Combining Prompts

Chain prompts together for comprehensive analysis:

Use morning-briefing, then use unusual-flow to dig into the top movers

Use pre-earnings for NVDA, then use greek-exposure to see dealer positioning

Use bullish-confluence to find candidates, then use ticker-analysis on the top result

Getting Started

1. Get an API Key

2. Install

Claude Code: ``bash claude mcp add unusualwhales -e UW_API_KEY=your_api_key -- npx -y @erikmaday/unusual-whales-mcp ``

Claude Desktop:

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unusualwhales": {
      "command": "npx",
      "args": ["-y", "@erikmaday/unusual-whales-mcp"],
      "env": {
        "UW_API_KEY": "your_api_key"
      }
    }
  }
}

3. Start Asking Questions

Once configured, just ask about the market. The Unusual Whales data will be used automatically.

Configuration (Optional)

The defaults work well for most users. All settings can be adjusted via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | UW_API_KEY | Your Unusual Whales API key | Required | | UW_RATE_LIMIT_PER_MINUTE | Max requests per minute | 120 | | UW_MAX_RETRIES | Retry attempts for failed requests | 3 | | UW_CIRCUIT_BREAKER_THRESHOLD | Failures before pausing requests | 5 | | UW_CIRCUIT_BREAKER_RESET_TIMEOUT | Milliseconds before retrying after failures | 30000 |

The server automatically handles rate limiting, retries failed requests with backoff, and temporarily pauses requests if the API is having issues (circuit breaker). See CONTRIBUTING.md for technical details.

Contributing

See CONTRIBUTING.md for development setup, testing, and contribution guidelines.

License

MIT

unusual-whales-mcp