Unusual Whales

You can access Unusual Whales data, including options flow analysis and market intelligence, through a lightweight MCP server. Run it locally as a standard MCP endpoint client, or integrate it into your existing MCP setup to query 33 tools across 12 data categories with real-time insights.

How to use

You use an MCP client to connect to the Unusual Whales MCP server. Start by launching the MCP server via the recommended command, then configure your client to connect using the provided stdio transport. Once connected, you can call any available tool to fetch stock data, market insights, congressional activity, dark pool data, ETF info, earnings calendars, and more. Use the server to automate data retrieval in your workflows or to build interactive prompts in your preferred MCP-enabled assistant.

How to install

Prerequisites: you need Node.js 18+ installed on your machine. You also need a valid Unusual Whales API key to access the data.

# Quick Start (run directly with npx)
npx unusualwhales-mcp

# Global installation
npm install -g unusualwhales-mcp

# Local installation in your project
npm install unusualwhales-mcp

Configuration and usage notes

Set your API key in the environment before starting the server. You can export it in your shell or place it in a .env file.

export UNUSUAL_WHALES_API_KEY=your_api_key_here

# Or create a .env file in your project root
# UNUSUAL_WHALES_API_KEY=your_api_key_here

MCP client configuration example

Configure your MCP client to connect to Unusual Whales using the provided stdio transport. Below is a representative configuration you can adapt for your client.

{
  "mcpServers": {
    "unusualwhales": {
      "type": "stdio",
      "name": "unusualwhales",
      "command": "npx",
      "args": ["unusualwhales-mcp"],
      "env": {
        "UNUSUAL_WHALES_API_KEY": "your_api_key_here"
      }
    }
  }
}

Environment variables

The server requires an API key to access Unusual Whales data. Provide it as an environment variable named UNUSUAL_WHALES_API_KEY.

Notes on usage across clients

You can also connect with the MCP client via the CLI by running the same npx command directly in your terminal, or integrate the server with compatible MCP clients such as Claude Desktop or VS Code.

Available tools

get_stock_info

Get comprehensive stock information for a ticker.

get_stock_flow_alerts

Retrieve options flow alerts for a ticker.

get_stock_flow_recent

Fetch recent options flow data.

get_stock_option_chains

Obtain option chains data for a ticker.

get_stock_greek_exposure

Analyze Greeks exposure for a stock.

get_stock_max_pain

Compute max pain for options contracts.

get_stock_iv_rank

Get implied volatility rank percentiles.

get_stock_volatility_stats

Provide volatility statistics for a stock.

get_market_tide

Get overall market sentiment indicator.

get_market_economic_calendar

Access the economic events calendar.

get_market_fda_calendar

Access FDA-related market events calendar.

get_market_spike

Get SPIKE volatility indicator.

get_market_total_options_volume

Fetch market-wide options volume.

get_congress_trader

Get congress member trading data.

get_congress_late_reports

Get late filings of congress trades.

get_congress_recent_trades

Get recent congressional trades.

get_darkpool_recent

Get recent dark pool prints.

get_darkpool_ticker

Get dark pool data for a specific ticker.

get_etf_exposure

Get ETF sector/geographic exposure.

get_etf_holdings

Get ETF holdings breakdown.

get_etf_in_outflow

Get ETF flow data.

get_etf_info

Get ETF information.

get_etf_weights

Get ETF sector weights.

get_earnings_afterhours

Get after-hours earnings data.

get_earnings_premarket

Get pre-market earnings data.

get_earnings_ticker

Get historical earnings for a ticker.

get_alerts

Get triggered user alerts.

get_alerts_configuration

Get alert configurations.

get_option_trades_flow_alerts

Get options flow alerts.

get_screener_analysts

Get analyst ratings screener.

get_screener_option_contracts

Get hottest option chains screener.

get_screener_stocks

Get stock screener results.

get_news_headlines

Get financial news headlines.