unusualwhales-mcp

v0.1.8

Published

4 months ago

MCP server for Unusual Whales financial data and analytics

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

Obtain an API key from Unusual Whales
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