Unusual Whales MCP

Inspired by erikmaday/unusual-whales-mcp - the original community MCP server for Unusual Whales by Erik Maday.

The official Unusual Whales MCP server. Connect any MCP-compatible client to 200+ market data endpoints covering options flow, dark pool, congressional trading, Greek exposure, volatility, futures, and more.

Quick Start

1. Get an API Key

Get your key at unusualwhales.com/settings/api-dashboard.

2. Connect

Remote (recommended) — no install, connects to the hosted endpoint:

# Claude Code
claude mcp add --transport http unusualwhales \
  https://api.unusualwhales.com/api/mcp \
  --header "Authorization: Bearer YOUR_KEY"

// Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS)
{
  "mcpServers": {
    "unusualwhales": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.unusualwhales.com/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_KEY"
      ]
    }
  }
}

Claude Desktop does not natively support remote MCP servers yet, so we use mcp-remote to bridge the connection. Requires Node.js 18+.

// Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "unusualwhales": {
      "type": "url",
      "url": "https://api.unusualwhales.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

// VS Code (.vscode/mcp.json) — uses "servers" instead of "mcpServers"
{
  "servers": {
    "unusualwhales": {
      "type": "url",
      "url": "https://api.unusualwhales.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

// Windsurf (~/.codeium/windsurf/mcp_config.json) — uses "serverUrl" instead of "url"
{
  "mcpServers": {
    "unusualwhales": {
      "serverUrl": "https://api.unusualwhales.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

After adding the config, fully quit and reopen your AI assistant. Just saving the file is not enough — the MCP server connects at startup.

# Claude Code
claude mcp add unusualwhales -e UW_API_KEY=YOUR_KEY -- npx -y @unusualwhales/mcp

// Claude Desktop, Cursor
{
  "mcpServers": {
    "unusualwhales": {
      "command": "npx",
      "args": ["-y", "@unusualwhales/mcp"],
      "env": {
        "UW_API_KEY": "YOUR_KEY"
      }
    }
  }
}

// VS Code (.vscode/mcp.json)
{
  "servers": {
    "unusualwhales": {
      "command": "npx",
      "args": ["-y", "@unusualwhales/mcp"],
      "env": {
        "UW_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Troubleshooting

3. Ask Questions

Once connected, just ask about the market in 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
Deep dive on NVDA - options, dark pool, insider activity

Tools

The server exposes tools across 16 data categories. Your MCP client will call them automatically based on your questions.

Public Stock Fundamentals and Technicals

The MCP now includes public-style stock tools that map directly to the stock fundamentals and technical indicator endpoints.

The grouped local-package tools uw_fundamentals and uw_technicals remain available for clients that prefer the existing action-based interface.

Prompts

The server includes 30+ ready-to-use analysis prompts. Ask to use any prompt by name.

Chain prompts for deeper analysis:

Use morning-briefing, then unusual-flow to dig into top movers
Use pre-earnings for NVDA, then greek-exposure to see dealer positioning
Use bullish-confluence to find candidates, then ticker-analysis on the top result

Configuration

All optional. The defaults work for most users.

Endpoint Schema

Every endpoint the server exposes is published as machine-readable JSON, generated from the same catalog the server registers from:

Both are regenerated with npm run docs and verified in CI, so they cannot drift from the server. To check the catalog against the live upstream API:

npm run fetch-spec   # download the current OpenAPI spec
npm run check-api    # report missing endpoints, unknown routes, and param drift

WebSocket channels (/api/socket/*) are intentionally not exposed: MCP is request/response. Use the REST endpoints directly for streaming.

Contributing

See CONTRIBUTING.md.

Acknowledgments

This project builds on the foundational work of Erik Maday, whose unusual-whales-mcp was the first community MCP server for Unusual Whales and demonstrated how to bring market data into the MCP ecosystem.

License

MIT - see LICENSE.

_{Originally inspired by the UW community MCP erikmaday/unusual-whales-mcp.}