What's In This Guide
Unusual Whales MCP · 100+ market-data endpoints
- What you are actually connecting: 100+ live market-data endpoints across 15 categories
- Where to get your API key, and the honest note on what it costs
- The 5 ways to connect it, starting with the no-files Claude Desktop method
- The one URL mistake that breaks everyone, and how to avoid it
- The best prompts: the built-in routines plus copy-paste questions by use case
What You're Actually Connecting
Before the setup, know what you're plugging in. The Unusual Whales MCP gives Claude 100+ live market-data endpoints across 15 categories, plus 30+ built-in analysis routines. You never have to know a tool name. You ask in plain English and Claude routes to the right data.
- Options Flow Unusual activity, the full tape, net flow by expiry and sector
- Dark Pool Large off-exchange prints with price-level context
- Congress Congressional trades, late filings, individual member activity
- Insider Insider buys and sells by ticker and by sector
- Institutions 13F filings, holdings, and ownership changes
- Greeks Gamma, delta, and vanna exposure by strike and expiry
- Earnings Schedules, history, and expected moves
- Shorts Short interest, FTDs, short-volume ratio, borrow rates
- Screeners Stock screener, options screener, analyst ratings
- Market Market tide, sector tide, economic and FDA calendars, correlations
- ETFs and Seasonality Holdings, flows, exposure, historical seasonal patterns
- News and Predictions Market headlines and prediction-market activity
1. Get Your API Key
- Go to unusualwhales.com/settings/api-dashboard (Settings → API Dashboard).
- Copy your API key and keep it handy for the next step.
2. Connect It to Claude
Claude Desktop, the easy way (No files)
No config files, no terminal. Set it up entirely from the app:
- Open Claude Desktop, then go to Settings → Connectors.
- Click Add Custom Connector.
- Fill in two fields. Name it Unusual Whales, and for the URL paste this (swap in your real key):
https://api.unusualwhales.com/api/mcp?token=YOUR_API_KEY Then restart. Save, then fully quit and reopen Claude Desktop. That's the whole job. Skip to the prompts.
Claude Code, Cursor, VS Code (Config)
If you live in a coding tool, use the block for your app. Swap YOUR_KEY for your real key, save, then fully restart the app.
Claude Code (one command)
claude mcp add --transport http unusualwhales \
https://api.unusualwhales.com/api/mcp \
--header "Authorization: Bearer YOUR_KEY" Claude Desktop, config-file method (needs Node.js 18+)
{
"mcpServers": {
"unusualwhales": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.unusualwhales.com/api/mcp",
"--header",
"Authorization: Bearer YOUR_KEY"
]
}
}
} 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 — note: uses "servers")
{
"servers": {
"unusualwhales": {
"type": "url",
"url": "https://api.unusualwhales.com/api/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
} The Best Prompts
Two ways to use this, both copy-paste. Start with the built-in routines you trigger by name, then steal the natural-language prompts by use case.
The built-in routines (just say the name)
The server ships with 30+ ready-made routines. You trigger them by asking Claude to run them. These are the ones worth memorizing.
- morning-briefing Market tide, earnings, and the key activity to start your day
- daily-summary Full overview: tide, sectors, flow, and dark pool
- unusual-flow A scan for unusual options activity right now
- dark-pool-scanner Large dark pool prints and institutional footprints
- congress-tracker Recent congressional trades with the patterns called out
- ticker-analysis Deep dive on a name: options, dark pool, insiders, catalysts
- pre-earnings Historical moves, IV, and positioning before earnings
- greek-exposure Gamma, delta, and vanna by strike (dealer positioning)
- bullish-confluence Where bullish flow, dark pool, and insider buying line up
- bearish-confluence Bearish flow, distribution, and insider selling
- iv-screener High and low IV-rank names for options strategies
- short-interest Short interest, FTDs, and squeeze potential
Natural-language prompts (just ask)
You don't need the routine names. Describe what you want and Claude routes to the right data. Copy any of these and swap the ticker.
Give me a full market overview right now: market tide, sector sentiment, the biggest options flow, notable dark pool prints, and anything on the economic calendar today. Keep it to the 5 things that actually matter.
Deep dive on NVDA. Pull today's options flow, any unusual activity, dark pool prints, recent insider transactions, short interest, and upcoming catalysts. Tell me what the smart money is doing and where the risk is.
Scan for unusual options flow today. Show me the tickers with the biggest net premium and the most aggressive directional bets, and flag which look like real conviction versus noise.
What have members of Congress bought and sold in the last two weeks? Group it by ticker, show the dollar size, and flag anyone trading ahead of a catalyst.
Walk me through next week's earnings calendar for large caps. For each, give me the expected move from options, the IV rank, and how the stock has historically moved on earnings.
Analyze dark pool activity for SPY over the last few sessions. Where are the biggest prints, what price levels are they clustered at, and what does that suggest about institutional positioning?
Find me stocks with high IV rank AND bullish options flow today. Then cross-check the top 3 against dark pool and insider activity and tell me which has the strongest confluence.
Show me the gamma exposure by strike for SPY for this Friday's expiry. Where is the biggest dealer gamma, and what does that imply for where price gets pinned or where moves accelerate?
Chain them (where it gets powerful)
The real edge is stacking routines into one request. Claude holds the thread the whole way.
Run morning-briefing. Then take the top mover from it and run a full ticker-analysis on it. Then check the gamma exposure on that name and tell me if the options market agrees with the flow.
Run bullish-confluence to find candidates. Take the strongest one, deep dive it, and tell me the bull case, the bear case, and what would make you change your mind.
Confirm It's Connected
After connecting and restarting, just ask Claude:
What's the options flow for AAPL today?
If it pulls live numbers, you're connected. If it can't, here's the fix for each common failure:
- Server won't connect Check the URL is exactly
https://api.unusualwhales.com/api/mcp. The wrong URL is the number-one cause. - Tools don't appear Fully quit and reopen the app. Saving the config isn't enough. Also check your JSON has no trailing commas.
- 401 Unauthorized Your key is wrong or inactive. Confirm it reads
Authorization: Bearer YOUR_KEYwith your real key. - 429, rate limited Default is 120 requests a minute. Slow down concurrent queries or upgrade your API plan.
- npx not found (nvm users) Claude Desktop doesn't inherit your shell PATH. Use the full path to npx in the config and add a PATH env entry, or just use the Connector method instead. Easiest fix: paste the error to Claude and say "my Unusual Whales MCP is throwing this, help me fix it."
The Data Was Never the Hard Part
Unusual Whales has had this data for years. The hard part was reading it, knowing which of fifty dashboards to open, what the numbers meant, and how to connect flow to dark pool to insider activity fast enough to matter.
That's the whole point of plugging it into Claude. You stop hunting through screens and start asking questions. "What's the smart money doing in semis this week?" is now a sentence, not a 40-minute research session.
Connect it once. Steal the prompts. Run morning-briefing before the open tomorrow and see how it feels to get the market read in thirty seconds instead of thirty minutes.