Unusual Whales MCP Server

A Model Context Protocol (MCP) server that provides access to the Unusual Whales API for financial data, options flow analysis, and market intelligence.

Features

• 🚀 Fast and lightweight - Direct API access without heavy dependencies
• 📊 Comprehensive data - 33 tools covering 12 financial data categories
• 🔄 Real-time insights - Options flow alerts, market sentiment, and live data
• 🏛️ Congressional tracking - Monitor politician trading activity
• 🌊 Dark pool analysis - Track institutional block trades
• 📈 Market intelligence - ETF flows, earnings data, and volatility metrics

Requirements

• Node.js 18+
• Valid Unusual Whales API key
• Compatible with Claude Desktop, VS Code, and other MCP clients

Installation

The server is available as an npm package and can be installed in multiple ways:

Quick Start

npx unusualwhales-mcp

Global Installation

npm install -g unusualwhales-mcp

Local Installation

npm install unusualwhales-mcp

Configuration

Environment Setup

1. Obtain an API key from Unusual Whales
2. Set the environment variable:

export UNUSUAL_WHALES_API_KEY=your_api_key_here

Or create a .env file:

UNUSUAL_WHALES_API_KEY=your_api_key_here

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

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

VS Code (via MCP extension)

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

Other MCP Clients

The server works with any MCP-compatible client. Use the command:

npx unusualwhales-mcp

Available Tools

📊 Stock Analysis

• get_stock_info - Get comprehensive stock information
• get_stock_flow_alerts - Get options flow alerts for a ticker
• get_stock_flow_recent - Get recent options flows
• get_stock_option_chains - Get option chains data
• get_stock_greek_exposure - Get Greeks exposure analysis
• get_stock_max_pain - Get max pain calculations
• get_stock_iv_rank - Get IV rank percentiles
• get_stock_volatility_stats - Get volatility statistics

🌊 Market Data

• get_market_tide - Get overall market sentiment indicator
• get_market_economic_calendar - Get economic events calendar
• get_market_fda_calendar - Get FDA calendar events
• get_market_spike - Get SPIKE volatility indicator
• get_market_total_options_volume - Get market-wide options volume

🏛️ Congressional & Insider Trading

• get_congress_trader - Get congress member trading data
• get_congress_late_reports - Get late filing reports
• get_congress_recent_trades - Get recent congressional trades

🌑 Dark Pool Analysis

• get_darkpool_recent - Get recent dark pool prints
• get_darkpool_ticker - Get dark pool data for specific ticker

📈 ETF Analysis

• 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

📅 Earnings & Events

• get_earnings_afterhours - Get after-hours earnings
• get_earnings_premarket - Get pre-market earnings
• get_earnings_ticker - Get historical earnings for ticker

🔔 Alerts & Screening

• 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 chains screener
• get_screener_stocks - Get stock screener results

📰 News

• get_news_headlines - Get financial news headlines

Usage Examples

Basic Stock Analysis

// Get recent options flows for AAPL
const flows = await server.callTool("get_stock_flow_recent", { 
  ticker: "AAPL" 
});

// Get comprehensive stock info
const info = await server.callTool("get_stock_info", { 
  ticker: "TSLA" 
});

Market Sentiment

// Get overall market sentiment
const tide = await server.callTool("get_market_tide", {});

// Get volatility spike indicator
const spike = await server.callTool("get_market_spike", {});

Congressional Trading

// Get recent congressional trades for NVDA
const congressTrades = await server.callTool("get_congress_recent_trades", { 
  ticker: "NVDA" 
});

// Get trades by specific congress member
const memberTrades = await server.callTool("get_congress_trader", { 
  name: "Nancy Pelosi" 
});

Dark Pool Activity

// Get recent dark pool activity
const darkPool = await server.callTool("get_darkpool_recent", { 
  limit: 50 
});

// Get dark pool data for specific ticker
const tickerDarkPool = await server.callTool("get_darkpool_ticker", { 
  ticker: "SPY" 
});

Using as a Package in Node.js Projects

This package can be imported and used directly in your Node.js applications, including web frameworks like Hono, Express, or Fastify.

Installation as Dependency

npm install unusualwhales-mcp

Basic Usage

import { UnusualWhalesMcp } from 'unusualwhales-mcp';

// Create MCP server instance
const mcpServer = new UnusualWhalesMcp();

// Get the server instance for integration
const server = mcpServer.getServer();

// Start with different transport types
await mcpServer.start('stdio');  // For MCP clients
await mcpServer.start('sse', { endpoint: '/sse', response: res });  // For HTTP SSE
await mcpServer.start('streamableHttp');  // For HTTP streaming

Integration with Hono Web Framework

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { UnusualWhalesMcp } from 'unusualwhales-mcp';

const app = new Hono();
const mcpServer = new UnusualWhalesMcp();

// Enable CORS for MCP endpoints
app.use('/mcp/*', cors({
  origin: '*',
  allowHeaders: ['Content-Type'],
  allowMethods: ['GET', 'POST', 'OPTIONS'],
}));

// SSE endpoint for MCP over HTTP
app.get('/mcp/sse', async (c) => {
  const response = c.env?.response || c.res;
  
  // Start MCP server with SSE transport
  await mcpServer.start('sse', { 
    endpoint: '/mcp/sse', 
    response: response 
  });
  
  return c.json({ status: 'SSE endpoint ready' });
});

// Streamable HTTP endpoint
app.post('/mcp/message', async (c) => {
  try {
    // Create streamable HTTP transport
    const transport = mcpServer.createStreamableHTTPTransport({
      sessionIdGenerator: () => crypto.randomUUID()
    });
    
    // Handle MCP message
    const body = await c.req.json();
    
    return c.json({ 
      status: 'message processed',
      sessionId: transport.sessionId 
    });
  } catch (error) {
    console.error('MCP endpoint error:', error);
    return c.json({ error: 'Internal server error' }, 500);
  }
});

// Direct API endpoints (bypassing MCP)
app.get('/api/stock/:ticker', async (c) => {
  try {
    const ticker = c.req.param('ticker');
    const server = mcpServer.getServer();
    
    // Call tool directly
    const result = await server.callTool('get_stock_info', { ticker });
    
    return c.json(result);
  } catch (error) {
    return c.json({ error: error.message }, 500);
  }
});

export default {
  port: 3000,
  fetch: app.fetch,
};

Environment Configuration

# Set your Unusual Whales API key
export UNUSUAL_WHALES_API_KEY=your_api_key_here

# Optional: Configure server settings
export MCP_SERVER_NAME=unusualwhales-mcp
export MCP_SERVER_VERSION=0.1.3

Advanced Usage with Custom Transport

import { UnusualWhalesMcp } from 'unusualwhales-mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

const mcpServer = new UnusualWhalesMcp();

// Create custom SSE transport
const customTransport = new SSEServerTransport('/custom-endpoint', response);

// Connect server with custom transport
await mcpServer.getServer().connect(customTransport);

// Or use the helper methods
const sseTransport = mcpServer.createSSETransport('/my-endpoint', response);
const httpTransport = mcpServer.createStreamableHTTPTransport({
  sessionIdGenerator: () => `session-${Date.now()}`
});

TypeScript Support

The package includes full TypeScript definitions:

import { UnusualWhalesMcp } from 'unusualwhales-mcp';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const mcpServer: UnusualWhalesMcp = new UnusualWhalesMcp();
const server: McpServer = mcpServer.getServer();

// Full type safety for all API calls
const stockInfo = await server.callTool('get_stock_info', { 
  ticker: 'AAPL' 
});

API Coverage

The server provides access to 81 API endpoints across 12 categories:

Category	Endpoints	Description
Alerts	2	Custom alerts and configurations
Congress	3	Congressional trading data
Darkpool	2	Dark pool trading analysis
Earnings	3	Earnings calendars and data
ETFs	5	ETF analysis and holdings
Group Flow	2	Grouped options flow data
Insider	4	Insider trading information
Institutions	6	Institutional holdings and activity
Market	9	Market-wide data and indicators
Net Flow	1	Net options flow by expiry
News	1	Financial news headlines
Option Contract	4	Individual contract analysis
Option Trades	2	Options flow and alerts
Screeners	3	Stock and options screening tools
Seasonality	4	Seasonal market patterns
Shorts	5	Short interest and volume data
Stock	27	Comprehensive stock analysis

Development

Local Development

# Clone the repository
git clone https://github.com/your-username/unusualwhales-mcp.git
cd unusualwhales-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your API key

# Build the project
npm run build

# Run the server
npm start

Available Scripts

• npm run build - Compile TypeScript and make executable
• npm run watch - Watch for changes and recompile
• npm run inspector - Launch MCP inspector for debugging
• npm run prepare - Prepare package for publishing

Project Structure

unusualwhales-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
template
└── README.md            # This file

Rate Limits

Please be aware of Unusual Whales API rate limits. The server includes:

• 30-second timeout for requests
• Proper error handling for rate limit responses
• Retry logic for transient failures

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

⚠️ Important: This software is for educational and research purposes only. Always verify data independently before making trading decisions. The authors are not responsible for any financial losses incurred from using this software.

Support

• Issues: GitHub Issues
• API Documentation: Unusual Whales API Docs

Related Projects

• Model Context Protocol - Official MCP implementation
• Claude Desktop - AI assistant with MCP support
• Unusual Whales - Financial data platform

---

Made with ❤️ for unusualwhales