unusual-whales/unusual-whales-official-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:
bash
# Claude Code
claude mcp add --transport http unusualwhales \
https://api.unusualwhales.com/api/mcp \
--header "Authorization: Bearer YOURKEY"
json
// Claude Desktop (~/Library/Application Support/Claude/claudedesktopconfig.json on macOS)
"mcpServers": {
"unusualwhales": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.unusualwhales.com/api/mcp",
"--header",
"Authorization: Bearer YOURKEY"
> Claude Desktop does not natively support remote MCP servers yet, so we use mcp-remote to bridge the connection. Requires Node.js 18+.
json
// Cursor (~/.cursor/mcp.json)
"mcpServers": {
"unusualwhales": {
"type": "url",
"url": "https://api.unusualwhales.com/api/mcp",
"headers": {
"Authorization": "Bearer YOURKEY"
json
// VS Code (.vscode/mcp.json) — uses "servers" instead of "mcpServers"
"servers": {
"unusualwhales": {
"type": "url",
"url": "https://api.unusualwhales.com/api/mcp",
"headers": {
"Authorization": "Bearer YOURKEY"
json
// Windsurf (~/.codeium/windsurf/mcpconfig.json) — uses "serverUrl" instead of "url"
"mcpServers": {
"unusualwhales": {
"serverUrl": "https://api.unusualwhales.com/api/mcp",
"headers": {
"Authorization": "Bearer YOURKEY"
> After adding the config, fully quit and reopen your AI assistant. Just saving the file is not enough — the MCP server connects at startup.
Local — runs on your machine (Node.js 20+)
bash
# Claude Code
claude mcp add unusualwhales -e UWAPIKEY=YOURKEY -- npx -y @unusualwhales/mcp
json
// Claude Desktop, Cursor
"mcpServers": {
"unusualwhales": {
"command": "npx",
"args": ["-y", "@unusualwhales/mcp"],
"env": {
"UWAPIKEY": "YOURKEY"
json
// VS Code (.vscode/mcp.json)
"servers": {
"unusualwhales": {
"command": "npx",
"args": ["-y", "@unusualwhales/mcp"],
"env": {
"UWAPIKEY": "YOURKEY"
Config file locations:
Claude Desktop (macOS): ~/Library/Application Support/Claude/claudedesktopconfig.json
Claude Desktop (Windows): %APPDATA%\Claude\claudedesktopconfig.json
Cursor: .cursor/mcp.json or ~/.cursor/mcp.json
VS Code: .vscode/mcp.json
Windsurf: ~/.codeium/windsurf/mcpconfig.json
### Troubleshooting
| Problem | Fix |
| Server not connecting | Make sure the URL is exactly https://api.unusualwhales.com/api/mcp. Common mistake: using unusualwhales.com/public-api/mcp (that's the docs page, not the server). |
| Tools not appearing | Fully quit and reopen your client after adding the config. Verify your JSON has no trailing commas. |
| 401 Unauthorized | Check your API key is correct and active. Remote config needs "Authorization: Bearer YOURKEY" in the --header arg. Local config needs UWAPIKEY in env. |
| npx not found (nvm users) | Claude Desktop doesn't inherit your shell PATH. Use the full path to npx in the command field (e.g. /Users/you/.nvm/versions/node/v20.x.x/bin/npx) and add "env": { "PATH": "/Users/you/.nvm/versions/node/v20.x.x/bin:/usr/local/bin:/usr/bin:/bin" }. |