# Unusual Whales MCP [Verified owner] [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/unusual-whales/unusual-whales-official-mcp  
**GitHub Stars:** 95  
**npm Downloads (last month):** 673  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/unusual-whales-mcp

## Description
The official Unusual Whales MCP server. Options flow, dark pool prints, congressional trades, Greek exposure, volatility, futures and prediction markets as MCP tools. Needs a UW API key.

## Tools
Capabilities this server exposes over MCP:

- **uw_stock** — Access UnusualWhales stock data including options chains, greeks, IV, OHLC candles, open interest, and more.

Available commands:
- info: Get stock information (ticker required)
- ohlc: Get OHLC candles (ticker, candle_size required; date, timeframe, end_date, limit optional)
- option_chains: Get option chains (ticker required; date, greeks optional)
- option_contracts: Get option contracts (ticker required; expiry, option_type, min_dte, max_dte, filters, limit optional)
- greeks: Get greeks data (ticker, expiry required; date optional)
- greek_exposure: Get gamma/delta/vanna exposure (ticker required; date, timeframe optional)
- greek_exposure_by_expiry: Get greek exposure by expiry (ticker required; date optional)
- greek_exposure_by_strike: Get greek exposure by strike (ticker required; date optional)
- greek_exposure_by_strike_expiry: Get greek exposure by strike and expiry (ticker, expiry required; date optional)
- gex_levels: Get GEX (gamma exposure) levels (ticker required; date optional)
- option_stance: Get option trade-stance ranking (ticker, stance required; limit, type, option_symbol, date optional)
- options_pulse: Get options pulse for a ticker (ticker required; date optional)
- greek_flow: Get greek flow (ticker required; date optional)
- greek_flow_by_expiry: Get greek flow by expiry (ticker, expiry required; date optional)
- iv_rank: Get IV rank (ticker required; date, timespan optional)
- interpolated_iv: Get interpolated IV (ticker required; date optional)
- max_pain: Get max pain (ticker required; date optional)
- oi_change: Get OI change (ticker required; date, limit, page, order optional)
- oi_per_expiry: Get OI per expiry (ticker required; date optional)
- oi_per_strike: Get OI per strike (ticker required; date optional)
- options_volume: Get options volume (ticker required; limit optional)
- volume_oi_expiry: Get volume/OI by expiry (ticker required; date optional)
- atm_chains: Get ATM chains for given expirations (ticker, expirations required)
- expiry_breakdown: Get expiry breakdown (ticker required; date optional)
- flow_per_expiry: Get flow per expiry (ticker required)
- flow_per_strike: Get flow per strike (ticker required; date optional)
- flow_per_strike_intraday: Get intraday flow per strike (ticker required; date, filter optional)
- flow_recent: Get recent flow (ticker required; side, min_premium optional)
- net_prem_ticks: Get net premium ticks (ticker required; date optional)
- nope: Get NOPE data (ticker required; date optional)
- stock_price_levels: Get stock price levels (ticker required; date optional)
- stock_volume_price_levels: Get volume price levels (ticker required; date optional)
- spot_exposures: Get spot exposures (ticker required; date optional)
- spot_exposures_by_expiry_strike: Get spot exposures by expiry/strike (ticker, expirations required; date, filters optional)
- spot_exposures_by_strike: Get spot exposures by strike (ticker required; date, filters optional)
- spot_exposures_expiry_strike: Get spot exposures for specific expiry (ticker, expirations required; date, strike filters optional)
- spot_exposures_by_expiry: DEPRECATED — Get spot GEX exposures by strike for a single expiry (ticker, expiry required; date, min_strike, max_strike optional)
- historical_risk_reversal_skew: Get risk reversal skew (ticker, expiry, delta required; date, timeframe optional)
- volatility_realized: Get realized volatility (ticker required; date, timeframe optional)
- volatility_stats: Get volatility stats (ticker required; date optional)
- volatility_term_structure: Get term structure (ticker required; date optional)
- volatility_anomaly: Get volatility anomaly score (ticker required; date optional)
- volatility_character: Get volatility character (ticker required; date optional)
- volatility_variance_risk_premium: Get variance risk premium (ticker required; date optional)
- stock_state: Get stock state (ticker required)
- quote: Get the latest trade, NBBO and per-session quote change statistics (ticker required)
- insider_buy_sells: Get insider buy/sells for stock (ticker required; limit optional)
- ownership: PREMIUM — Get ownership data (ticker required; limit optional). Requires premium API plan, contact support@unusualwhales.com to upgrade
- tickers_by_sector: Get tickers in sector (sector required)
- ticker_exchanges: Get mapping of all tickers to their exchanges (no params required)
- flow_alerts: Get flow alerts for a specific ticker (ticker required; limit, is_ask_side, is_bid_side optional)
- fundamental_breakdown: Get fundamental financial data including EPS, revenue, dividends, share counts, and revenue breakdowns (ticker required)
- **uw_options** — Access UnusualWhales option contract data including flow, historic prices, intraday data, and volume profiles.

Available commands:
- flow: Get option contract flow (id required; side, min_premium, limit, date optional)
- historic: Get historic option contract data (id required; limit optional)
- intraday: Get intraday option contract data (id required; date optional)
- volume_profile: Get volume profile for option contract (id required; date optional)

The 'id' parameter is the option contract symbol (e.g., AAPL240119C00150000).
- **uw_flow** — Access UnusualWhales options flow data including flow alerts, full tape, net flow, group flow, and lit exchange flow.

Available commands:
- flow_alerts: Get flow alerts with extensive filtering options
- flow_alert: Get a single flow alert by ID with all constituent trades (id required; older_than optional). For multi-leg alerts returns all related legs; for RepeatedHits returns all transactions.
- full_tape: Get full options tape for a date (date required)
- net_flow_expiry: Get net flow by expiry date (date optional)
- group_greek_flow: Get greek flow (delta & vega) for a flow group (flow_group required; date optional)
- group_greek_flow_expiry: Get greek flow by expiry for a flow group (flow_group, expiry required; date optional)
- lit_flow_recent: Get recent lit exchange trades across the market
- lit_flow_ticker: Get lit exchange trades for a specific ticker (ticker required)
- exchange_breakdown: Get exchange & trade-code breakdown for a date (date required; ticker, by_trade_code, min_premium, limit, page, order optional)
- optionable_tickers: Get the list of optionable tickers (ticker optional)
- option_trades: Filter the full option trades tape — same data and filters as the live options flow page (all params optional)
- multi_leg_trades: Get detected multi-leg strategies (verticals, condors, butterflies, calendars, diagonals) with net price, premium and greeks (all params optional)
- multi_leg_legs: Get the individual legs of one multi-leg strategy (id required)

Flow groups: airline, bank, basic materials, china, communication services, consumer cyclical, consumer defensive, crypto, cyber, energy, financial services, gas, gold, healthcare, industrials, mag7, oil, real estate, refiners, reit, semi, silver, technology, uranium, utilities

Flow alerts filtering options include: ticker, premium range, volume range, OI range, DTE range, and more.
Lit flow filtering options include: premium range, size range, volume range, and timestamp filters.
- **uw_market** — Access UnusualWhales market-wide data including market tide, sector ETFs, economic calendar, FDA calendar, and more.

Available commands:
- market_tide: Get market tide data showing net premium flow (date optional; otm_only, interval_5m optional)
- sector_tide: Get sector-specific tide (sector required; date optional)
- etf_tide: Get ETF-based tide (ticker required; date optional)
- sector_etfs: Get SPDR sector ETF statistics
- economic_calendar: Get economic calendar events
- fda_calendar: Get FDA calendar (announced_date_min/max, target_date_min/max, drug, ticker, limit optional)
- correlations: Get correlations between tickers (tickers required; interval, start_date, end_date optional)
- insider_buy_sells: Get total insider buy/sell statistics (limit optional)
- oi_change: Get top OI changes (date, limit, order optional)
- top_net_impact: Get top tickers by net premium (date, issue_types, limit optional)
- total_options_volume: Get total market options volume (limit optional)
- options_pulse_sectors: Get options pulse by sector/industry (date optional)
- options_pulse_top: Options pulse scanner across the market (direction, date, ticker, min_score, max_score, min_txn, limit optional)
- options_pulse_total: Get market-wide options pulse (date optional)
- volatility_anomaly_top: Get top volatility anomalies (direction required; date, limit optional)
- volatility_character_top: Get top volatility character (date, limit, sort, dir optional)
- vix_term_structure: Get VIX term structure (history_days optional)
- **uw_darkpool** — Access UnusualWhales darkpool trade data.

Available commands:
- recent: Get recent darkpool trades across the market
- ticker: Get darkpool trades for a specific ticker
- price_levels: Get darkpool & lit volume concentration by price level for a ticker (ticker required; date optional)

Filtering options include premium range, size range, and volume range.
- **uw_congress** — Access UnusualWhales congress trading data including trades by congress members.

Available commands:
- recent_trades: Get recent trades by congress members
- late_reports: Get recent late reports by congress members
- congress_trader: Get trades by a specific congress member (name required)
- politicians: List politicians with trade data (trade count, first/last trade date, party, chamber, gender). Optional last_traded_within_months filter.
- **uw_insider** — Access UnusualWhales insider trading data including transactions and flow.

Available commands:
- transactions: Get insider transactions with filters. Use ticker_symbol for comma-separated tickers (e.g., AAPL,INTC)
- sector_flow: Get aggregated insider flow for a sector (sector required)
- ticker_flow: Get aggregated insider flow for a ticker (ticker required)
- insiders: Get all insiders for a ticker (ticker required)
- **uw_institutions** — Access UnusualWhales institutional holdings and ownership data.

Available commands:
- list: List institutions with filters
- holdings: Get holdings for an institution (name required)
- activity: Get trading activity for an institution (name required)
- activity_v2: Get trading activity v2 with enhanced data for an institution (name required; date, start_date, end_date optional)
- sectors: Get sector exposure for an institution (name required)
- ownership: Get institutional ownership of a ticker (ticker required)
- latest_filings: Get latest institutional filings
- **uw_earnings** — Access UnusualWhales earnings data including premarket and afterhours earnings schedules.

Available commands:
- premarket: Get premarket earnings for a date
- afterhours: Get afterhours earnings for a date
- ticker: Get historical earnings for a ticker (ticker required)
- **uw_etf** — Access UnusualWhales ETF data including holdings, exposure, inflows/outflows, and weights.

Available commands:
- info: Get ETF information (ticker required)
- holdings: Get ETF holdings (ticker required)
- exposure: Get ETFs that hold a ticker (ticker required)
- in_outflow: Get ETF inflow/outflow data (ticker required)
- weights: Get sector and country weights (ticker required)
- **uw_screener** — Access UnusualWhales screeners for stocks, options, and analysts.

Available commands:
- stocks: Screen stocks with various filters
- option_contracts: Screen option contracts with filters
- analysts: Screen analyst ratings
- unusual_activity: Get option contracts flagged as unusual — the API equivalent of the live options flow "unusual" view (all params optional)
- **uw_shorts** — Access UnusualWhales short selling data including short interest, FTDs, and volume.

Available commands:
- data: Get short data for a ticker (ticker required)
- ftds: Get failure to deliver data (ticker required)
- interest_float: Get short interest as percent of float (ticker required)
- volume_ratio: Get short volume and ratio (ticker required)
- volumes_by_exchange: Get short volumes by exchange (ticker required)
- interest_float_v2: Get short interest as percent of float v2 with enhanced data (ticker required)
- short_screener: Screen for stocks by short interest metrics (all params optional)
- **uw_seasonality** — Access UnusualWhales seasonality data showing historical performance patterns.

Available commands:
- market: Get market-wide seasonality data
- performers: Get top/bottom performers for a month (month required, 1-12)
  Optional filters: min_years, ticker_for_sector, s_p_500_nasdaq_only, min_oi, limit, order, order_direction
- monthly: Get monthly seasonality for a ticker (ticker required)
- year_month: Get year-month breakdown for a ticker (ticker required)
- **uw_news** — Access UnusualWhales news headlines.

Available commands:
- headlines: Get news headlines with optional filters (ticker, sources, search_term, major_only, page)
- **uw_alerts** — Access UnusualWhales user alerts and configurations.

Available commands:
- alerts: Get triggered alerts for the user
- configurations: Get alert configurations
- filters: Get the filter fields and accepted values available per alert type, plus which types this account may create
- query_grammar: Get the alert query language grammar — targets, syntax, fields, functions, operators, scopes and examples (target optional)

Call 'filters' and 'query_grammar' before constructing an alert configuration: they describe exactly which fields, values and expressions are valid.
- **uw_crypto** — Access UnusualWhales crypto data including prices, OHLC candles, whale trades, and whale transactions across 3 blockchains.

Available commands:
- state: Get current state for a crypto pair with 24h OHLCV data (pair required)
- ohlc: Get OHLC candles for a crypto pair (pair, candle_size required; limit, date optional)
- whales_recent: Get recent large crypto whale trades (limit optional)
- whale_transactions: Get whale transactions across blockchains (limit, blockchain, token_symbol optional)

Supported candle sizes: 1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 1w
Supported blockchains: ethereum, bitcoin, solana, polygon, arbitrum, avalanche, binance_smart_chain, cardano, dogecoin, fantom, optimism, polkadot, ripple, tron
- **uw_fundamentals** — Access fundamental financial data for stocks including financial statements, earnings, and revenue breakdowns.

Available commands:
- fundamental_breakdown: Get fundamental breakdown with revenue segments, EPS, RSU data, and dividends for a ticker
- financials: Get combined financial data (income statements, balance sheets, cash flows, and earnings) for a ticker
- income_statements: Get income statement data (revenue, expenses, net income, EBITDA, etc.)
- balance_sheets: Get balance sheet data (assets, liabilities, equity, debt, etc.)
- cash_flows: Get cash flow data (operating, investing, financing cash flows, capex, dividends, etc.)
- financial_earnings: Get reported and estimated EPS, earnings surprises
- **uw_technicals** — Access technical indicator data for stocks.

Available commands:
- technical_indicator: Get technical indicator time series data for a ticker

Supported indicators: SMA, EMA, RSI, MACD, BBANDS, STOCH, ADX, ATR, OBV, VWAP, CCI, WILLR, AROON, MFI
- **uw_predictions** — Access UnusualWhales prediction market data including unusual activity, whale traders, smart money, insiders, market details, positions, liquidity, and user profiles.

Available commands:
- unusual: Get prediction markets with unusual activity (categories, limit, offset optional)
- whales: Get large prediction market traders
- smart_money: Get profitable prediction market traders (categories, min_price, max_price optional)
- insiders: Get potential insider activity on prediction markets
- search_users: Search for prediction market users by query (q required)
- market: Get prediction market details for a given asset (asset_id required)
- positions: Get positions for a given prediction market asset (asset_id required)
- liquidity: Get liquidity data for a given prediction market asset (asset_id required)
- user: Get a prediction market user profile (user_id required)

Categories: Crypto, Culture, Finance, Politics, Science, Sports, Technology
- **uw_potus** — Access UnusualWhales data on the President of the United States, including social-media posts and the public schedule. Useful for tracking potentially market-moving statements and events.

Available commands:
- posts: Get the President's recent posts (limit, page, search_term optional)
- schedule: Get the President's public schedule (date, limit, page optional)
- **get_fundamental_breakdown** — Get filing-based fundamentals for a ticker, including earnings, revenue, cash flow, dividends, EPS, balance sheet trends, and revenue breakdowns by product or geography.
Use this for company financial statement analysis and medium/long-term fundamental context.
- **get_stock_financials** — Get combined stock financials for a ticker, including income statements, balance sheets, cash flows, and earnings.
- **get_income_statements** — Get income statement data for a ticker, including revenue, gross profit, operating income, EBITDA, and net income.
- **get_balance_sheets** — Get balance sheet data for a ticker, including assets, liabilities, equity, debt structure, and shares outstanding.
- **get_cash_flows** — Get cash flow statement data for a ticker, including operating, investing, and financing cash flows, capex, dividends, and buybacks.
- **get_earnings_history** — Get earnings history for a ticker with reported EPS, estimated EPS, surprise amount, surprise percentage, report date, and report timing.
- **get_technical_indicator** — Get a technical indicator time series for a ticker.
Supports: SMA, EMA, RSI, MACD, BBANDS, STOCH, ADX, ATR, OBV, VWAP, CCI, WILLR, AROON, MFI.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `UW_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Unusual Whales MCP does

The Unusual Whales MCP MCP server makes Unusual Whales market data available to MCP-compatible AI clients. The service covers more than 200 market-data endpoints across stock, options, flow, dark pool, congress, insider, institutions, market, earnings, ETF, shorts, seasonality, screener, and news categories.

Its explicitly documented stock-data tools include filing-based fundamental breakdowns, combined financial statements, income statements, balance sheets, cash flows, earnings history, and technical-indicator series. The technical tool supports SMA, EMA, RSI, MACD, Bollinger Bands, stochastic, ADX, ATR, OBV, VWAP, CCI, Williams %R, Aroon, and MFI indicators.

## How it works

The remote deployment is available at `https://api.unusualwhales.com/api/mcp` and accepts the API key as a Bearer authorization header. The local option runs the published `@unusualwhales/mcp` npm package and reads the key from `UW_API_KEY`.

After the client connects, it can select tools based on natural-language requests. Example requests include checking a ticker’s options flow, finding recent congressional trades, reviewing dark pool activity, examining max pain for an expiry, or combining options, dark pool, and insider information for a ticker.

## Setup and configuration

An Unusual Whales API key is required. Keys are obtained through the API dashboard on unusualwhales.com. Remote configuration is supported for Claude Code, Claude Desktop through the `mcp-remote` bridge, Cursor, VS Code, and Windsurf. Claude Desktop’s remote setup requires Node.js 18 or newer because it uses that bridge.

For local execution, the package requires Node.js 20 or newer. Configure `UW_API_KEY` in the client’s MCP server environment, then restart the client completely so it loads the server at startup. The documented local configurations cover Claude Code, Claude Desktop, Cursor, and VS Code.

The Unusual Whales MCP MCP server uses different configuration field names in some clients: VS Code uses `servers`, Cursor uses `url`, and Windsurf uses `serverUrl`. For remote connections, use the API endpoint exactly as documented rather than the public API documentation page.

## Tools and capabilities

- Query options chains, Greeks, implied-volatility data, candles, open interest, quotes, max pain, and volatility.
- Inspect options flow, trade tapes, multi-leg strategies, expiry flow, and sector flow.
- Review dark pool transactions with NBBO context and price-level filtering.
- Retrieve congressional, insider, and institutional activity, including 13F holdings and ownership changes.
- Analyze market tides, sectors, economic and FDA calendars, earnings, ETFs, short interest, borrow rates, seasonality, screeners, and market news.
- Retrieve financial statements, EPS history, filing-based fundamentals, and technical-indicator series.

## Limitations and notes

A valid and active API key is required; an invalid key can produce a 401 response. Futures data requires the Advanced tier or a `futures` add-on. Politician portfolios, recent trades, and holdings require a premium upgrade through Unusual Whales support.

Clients may not display tools until they are fully quit and reopened after configuration changes. Claude Desktop may also need the full filesystem path to `npx` when its shell PATH does not include Node.js, such as in some nvm installations. The README identifies the project license as MIT.

_Full upstream README: https://allmcps.com/mcp/unusual-whales-mcp/readme_

