MCPgee
MCPgee
MCPgeeMCPgee

Unusual Whales

v1.0.0•Finance & Fintech•stable

MCP Server for the Unusual Whales REST API

unusualwhalesmcpai-integration
Share:
10
Stars
0
Downloads
0
Weekly
0/5
View on GitHub

What is Unusual Whales?

Unusual Whales is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server for the unusual whales rest api

MCP Server for the Unusual Whales REST API

This server falls under the Finance & Fintech category on MCPgee, the world's largest MCP server directory with 33,000+ servers.

Features

  • MCP Server for the Unusual Whales REST API

Use Cases

Access Unusual Whales REST API for options market analysis.
danwagnerco

Maintainer

LicenseMIT
Languagepython
Versionv1.0.0
UpdatedJan 14, 2026
Statushealthy
Maintenanceactive

Works with

ClaudeOpenAIwindowsmacoslinux
View SourceBrowse All Servers

Installation

Manual Installation

npx unusualwhales

Configuration

Configuration Details

Config File

claude_desktop_config.json

Performance

Response Metrics

Response Time< 200ms
ThroughputMedium

Resource Usage

Memory UsageLow
CPU UsageLow

How to Set Up and Use Unusual Whales

The Unusual Whales MCP Server connects AI assistants to the Unusual Whales options flow API, exposing real-time options flow alerts so you can query unusual market activity, sweeps, floor trades, and earnings-related options positioning directly from your AI client. It is built with FastMCP and the httpx library, and requires a paid Unusual Whales API token to access live market data.

Prerequisites

  • Python 3.11 or higher installed
  • uv package manager (pip install uv) or pip
  • An active Unusual Whales account with API access
  • UNUSUAL_WHALES_API_TOKEN environment variable set
  • Claude Desktop or another MCP-compatible client
1

Clone the repository

Clone the mcp-server-unusualwhales repository from GitHub to your local machine.

git clone https://github.com/danwagnerco/mcp-server-unusualwhales.git
cd mcp-server-unusualwhales
2

Install dependencies with uv

Use uv to create a virtual environment and install the required packages including httpx, mcp[cli], and polars.

uv venv
source .venv/bin/activate
uv pip install -e .
3

Set your Unusual Whales API token

Export your Unusual Whales API token as an environment variable. This token is read by the server at startup via os.getenv('UNUSUAL_WHALES_API_TOKEN').

export UNUSUAL_WHALES_API_TOKEN=your_api_token_here
4

Add the server to Claude Desktop config

Edit your Claude Desktop configuration file to register the MCP server. On macOS this file is at ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "unusualwhales": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-server-unusualwhales",
        "run",
        "mcp",
        "run",
        "src/mcp_server_unusualwhales/server.py"
      ],
      "env": {
        "UNUSUAL_WHALES_API_TOKEN": "your_api_token_here"
      }
    }
  }
}
5

Restart Claude Desktop

Quit and reopen Claude Desktop so it picks up the new MCP server configuration. Verify the server appears in the tools panel.

Unusual Whales Examples

Client configuration

Complete claude_desktop_config.json entry for the Unusual Whales MCP server using uv to run the FastMCP server.

{
  "mcpServers": {
    "unusualwhales": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/yourname/mcp-server-unusualwhales",
        "run",
        "mcp",
        "run",
        "src/mcp_server_unusualwhales/server.py"
      ],
      "env": {
        "UNUSUAL_WHALES_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Prompts to try

Example natural language prompts to use with the Unusual Whales MCP server once configured.

- "Show me the latest options flow alerts for AAPL with a minimum premium of $100,000"
- "Find all put sweeps from the last hour with at least 500 contracts"
- "Get flow alerts for ETFs that are out of the money with DTE between 7 and 30 days"
- "Show me floor trades on large cap stocks today"
- "Find call options alerts with a volume to open interest ratio above 2.0"

Troubleshooting Unusual Whales

Server returns 401 Unauthorized

Ensure UNUSUAL_WHALES_API_TOKEN is correctly set in the env block of your claude_desktop_config.json. The token must match the one from your Unusual Whales account dashboard. Do not include 'Bearer ' prefix — the server constructs the Authorization header automatically.

Rate limit exceeded error (429)

The Unusual Whales API enforces rate limits per plan tier. Reduce the frequency of requests or upgrade your Unusual Whales subscription. Add delays between queries when making multiple requests in succession.

uv command not found when Claude Desktop starts

Provide the full absolute path to the uv binary in the command field, e.g. "/Users/yourname/.local/bin/uv", or install uv globally with pip install uv and ensure it is on the system PATH.

Frequently Asked Questions about Unusual Whales

What is Unusual Whales?

Unusual Whales is a Model Context Protocol (MCP) server that mcp server for the unusual whales rest api It connects AI assistants to external tools and data sources through a standardized interface.

How do I install Unusual Whales?

Follow the installation instructions on the Unusual Whales GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.

Which AI clients work with Unusual Whales?

Unusual Whales works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.

Is Unusual Whales free to use?

Yes, Unusual Whales is open source and available under the MIT license. You can use it freely in both personal and commercial projects.

Learn More About MCP Servers

Getting Started with MCP

Set up your first MCP server in minutes

MCP Setup Guide

Configure MCP in Claude, Cursor & VS Code

All MCP Tutorials

18+ hands-on guides for developers

MCP FAQ

40+ answers about Model Context Protocol

Unusual Whales Alternatives — Similar Finance & Fintech Servers

Looking for alternatives to Unusual Whales? Here are other popular finance & fintech servers you can use with Claude, Cursor, and VS Code.

ValueCell

★ 10.7k

ValueCell is a community-driven, multi-agent platform for financial applications.

Vibe Trading

★ 8.1k

'Vibe-Trading: Your Personal Trading Agent'

Quantdinger

★ 6.2k

AI quantitative trading platform for crypto, stocks, and forex with backtesting, live trading, market data, and multi-agent research.vibe-trading ,trading-agents,ai-trader,ai-trading

TradingView

★ 2.8k

Real-time crypto & stock screening, advanced technical indicators, Bollinger Bands intelligence, candlestick patterns + native Claude Desktop integration. Multi-exchange (Binance, KuCoin, Bybit+). Open-source AI trading infrastructure.

Financial Datasets

★ 2.1k

Provides access to comprehensive financial data including income statements, balance sheets, cash flow statements, stock prices, company news, SEC filings, and cryptocurrency information with built-in financial ratio analysis.

Stripe

★ 1.6k

The Stripe Model Context Protocol server allows you to integrate with Stripe APIs through function calling. This protocol supports various tools to interact with different Stripe services.

Browse More Finance & Fintech MCP Servers

Explore all finance & fintech servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.

Finance & FintechBrowse All Servers

Quick Config Preview

{ "mcpServers": { "unusualwhales": { "command": "npx", "args": ["-y", "unusualwhales"] } } }

Add this to your claude_desktop_config.json or .cursor/mcp.json

Read the full setup guide →

Ready to use Unusual Whales?

Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.

33,000+ ServersFree & Open SourceStep-by-Step Guides
Explore All ServersRead Our Guides