stock-scanner-mcp

A modular MCP server that gives Claude Code real-time access to stock and crypto market data. Scan markets, check technicals, monitor insider trades, track earnings, analyze options flow, and more — all from your terminal.

54 tools across 11 modules — 8 modules work with zero API keys.

What You Can Do

"What are the top gaining stocks today?"
"Show me technicals for AAPL on the hourly timeframe"
"Any insider trades for TSLA in the last 30 days?"
"What's the options chain for AAPL expiring next Friday?"
"What's the current fed funds rate and CPI trend?"
"Convert $10,000 USD to EUR"

Highlights

• Stock scanning — screen by price, RSI, volume, market cap with custom filters
• Technical analysis — RSI, MACD, Bollinger Bands, moving averages, pivots across multiple timeframes
• Options flow — chains with Greeks, unusual activity detection, max pain, implied move
• Insider trades — parsed Form 4 transactions with buy/sell/grant details
• Earnings & news — calendar, analyst ratings, company news, short interest
• Crypto — real-time quotes, technicals, trending coins, market stats
• Macro — CPI, GDP, fed funds rate, economic calendar, yield curve data
• Forex — 31 currency pairs from ECB, conversion, historical rates
• Sentiment — CNN Fear & Greed Index, Crypto Fear & Greed

Quick Start

1. Add MCP server to Claude Code

Add to ~/.claude.json (global) or .mcp.json (per-project):

{
  "mcpServers": {
    "stock-scanner": {
      "command": "npx",
      "args": ["-y", "stock-scanner-mcp"]
    }
  }
}

This gives you 36 tools immediately — no API keys needed.

2. Install trading skills (optional, recommended)

npx -p stock-scanner-mcp stock-scanner-install-skills

This installs 17 slash commands like /morning-briefing, /analyze-stock AAPL, /risk-check TSLA that orchestrate multiple tools into professional analysis workflows.

3. Add API keys for full access (optional)

All three keys are free — no credit card required:

Add them to your MCP config:

{
  "mcpServers": {
    "stock-scanner": {
      "command": "npx",
      "args": ["-y", "stock-scanner-mcp"],
      "env": {
        "FINNHUB_API_KEY": "your-key-here",
        "ALPHA_VANTAGE_API_KEY": "your-key-here",
        "FRED_API_KEY": "your-key-here"
      }
    }
  }
}

## Trading Skills

17 ready-made workflows that chain multiple tools into structured analysis. Each skill orchestrates 5-14 tools in parallel and outputs a verdict with direction, confidence, and key levels.

| Category | Skills | What They Do |
|----------|--------|-------------|
| **Daily Routines** | `/morning-briefing`, `/market-close-recap`, `/crypto-briefing` | Pre-market scan, EOD recap, crypto overview |
| **Analysis** | `/analyze-stock TICKER`, `/compare TICKER1 TICKER2`, `/analyze-crypto COIN` | Deep dives and side-by-side comparisons |
| **Strategies** | `/swing-setup`, `/earnings-play TICKER`, `/options-flow TICKER`, `/dividend-screen` | Swing trades, earnings options, smart money, income screen |
| **Macro** | `/macro-dashboard`, `/fed-watch`, `/sector-rotation` | Economic indicators, Fed outlook, sector rotation |
| **Risk** | `/insider-tracker TICKER`, `/smart-money TICKER`, `/risk-check TICKER` | Insider trades, institutional flow, pre-trade risk scorecard |

Skills degrade gracefully when optional API keys are missing. See [skills/README.md](skills/README.md) for the full catalog.

<details>
<summary>Install options</summary>

```bash
npx -p stock-scanner-mcp stock-scanner-install-skills                    # all skills
npx -p stock-scanner-mcp stock-scanner-install-skills --scope project    # project only
npx -p stock-scanner-mcp stock-scanner-install-skills --category macro   # one category
npx -p stock-scanner-mcp stock-scanner-install-skills --list             # list without installing
npx -p stock-scanner-mcp stock-scanner-install-skills --force            # overwrite existing

Manual: git clone this repo and cp -r skills/*/ ~/.claude/skills/

Modules

Modules auto-enable when their API key is set. No-key modules are always enabled.

Configuration

CLI Options

stock-scanner-mcp --modules tradingview,sec-edgar    # Enable specific modules only
stock-scanner-mcp --default-exchange NYSE             # Set default exchange
stock-scanner-mcp --help                              # Show all options

HTTP Sidecar

An optional HTTP server exposing all tools as REST endpoints for non-MCP integrations (trading bots, chat UIs, LLM pipelines).

npx stock-scanner-sidecar              # Start on port 3100
npx stock-scanner-sidecar --port 8080  # Custom port

55 endpoints including /tradingview/quote, /options/chain, /frankfurter/convert, and more. See wiki for the full route table.

Rate Limits

All modules use in-memory TTL caching to minimize API calls.

Development

npm install && npm run build && npm test
npm run lint          # TypeScript type checking
npm run validate-tools # Tool description quality check

src/
├── index.ts              # MCP server entry + prompt definitions
├── config.ts             # CLI arg parsing
├── registry.ts           # Module auto-discovery and filtering
├── modules/
│   ├── tradingview/      # 10 tools — stock scanning, quotes, technicals, sectors, indices
│   ├── tradingview-crypto/ # 4 tools — crypto scanning and technicals
│   ├── sec-edgar/        # 6 tools — filings, insider trades, holdings
│   ├── coingecko/        # 3 tools — crypto market data
│   ├── options/          # 5 tools — options chains, Greeks, unusual activity, implied move
│   ├── options-cboe/     # 1 tool  — CBOE put/call ratio sentiment
│   ├── finnhub/          # 9 tools — quotes, news, earnings, analyst ratings, short interest
│   ├── alpha-vantage/    # 5 tools — quotes, fundamentals, dividends
│   ├── fred/             # 4 tools — economic calendar, indicators, historical data
│   ├── sentiment/        # 2 tools — Fear & Greed indexes (market + crypto)
│   └── frankfurter/      # 5 tools — forex exchange rates (ECB, 31 currencies)
├── sidecar/
│   ├── index.ts          # HTTP sidecar entry point (port 3100)
│   └── server.ts         # HTTP request handler (55 endpoints)
└── shared/
    ├── http.ts           # HTTP client with timeouts and key sanitization
    ├── cache.ts          # In-memory TTL cache
    ├── types.ts          # ToolDefinition, ToolResult, helpers
    ├── resolver.ts       # Ticker/exchange resolution
    └── utils.ts          # withMetadata error wrapper

License

MIT