Unusual Whales

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

Sign up at Unusual Whales and get your API key.

2. Install

Claude Code:

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