stock-scanner-mcp

A modular MCP (Model Context Protocol) server that gives Claude Code real-time access to stock and crypto market data. Scan markets, check technicals, monitor insider trades, track earnings and economic events — all from your terminal.

54 tools across 11 modules — 8 modules work with zero API keys. 16 trading skills — ready-made workflows like /morning-briefing, /earnings-play AAPL, /risk-check TSLA.

Wiki — Full tool reference, example prompts, advanced strategies, and troubleshooting guide.

Quick Start

npx stock-scanner-mcp

Or install globally:

npm install -g stock-scanner-mcp
stock-scanner-mcp

Setup with Claude Code

Add to your Claude Code MCP config (~/.claude.json or project .mcp.json):

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

With API keys (optional, enables all 54 tools):

{
  "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"
      }
    }
  }
}

Modules

Modules auto-enable when their required environment variables are set. Modules with no required key are always enabled.

Available Tools (49 total)

TradingView — Stock Scanning (no API key)

TradingView — Crypto (no API key)

SEC EDGAR — Filings & Ownership (no API key)

CoinGecko — Crypto Intelligence (no API key)

Options — Chains, Greeks & Unusual Activity (no API key)

Options CBOE — Put/Call Sentiment (no API key)

Finnhub — News, Earnings & Macro (requires FINNHUB_API_KEY)

Alpha Vantage — Fundamentals & History (requires ALPHA_VANTAGE_API_KEY)

FRED — US Economic Data (requires FRED_API_KEY)

Sentiment — Fear & Greed Indexes (no API key)

Configuration

Environment Variables

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

MCP Prompts

The server includes built-in analysis workflows:

Example Usage in Claude Code

Once configured, just ask Claude naturally:

• "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 trending in crypto right now?"
• "Find stocks with unusual volume today"
• "What earnings are coming up this week?"
• "What's the current fed funds rate and CPI inflation trend?"
• "Show me upcoming high-impact economic events"
• "What's the short interest on GME?"
• "Get Apple's dividend history"
• "What's the options chain for AAPL expiring next Friday?"
• "Any unusual options activity on TSLA?"
• "What's the max pain for SPY this week?"
• "Show me the put/call ratio trend for the last 30 days"
• "What's the current Fear & Greed Index?"
• "How is crypto sentiment right now?"

Trading Skills for Claude Code

16 ready-made trading workflows that chain multiple tools into professional analysis. Install them as Claude Code slash commands and run full analyses with a single command.

Install Skills

# Install all skills (recommended)
npx -p stock-scanner-mcp stock-scanner-install-skills

# Install to project scope only
npx -p stock-scanner-mcp stock-scanner-install-skills --scope project

# Install one category
npx -p stock-scanner-mcp stock-scanner-install-skills --category macro

# List available skills
npx -p stock-scanner-mcp stock-scanner-install-skills --list

Note: npx stock-scanner-mcp install-skills also works if the package is already cached. The -p stock-scanner-mcp flag tells npx which package to download, while stock-scanner-install-skills is the bin command within that package.

git clone https://github.com/yyordanov-tradu/stock-scanner-mcp.git
cp -r stock-scanner-mcp/skills/*/ ~/.claude/skills/

Then in Claude Code, type /morning-briefing, /analyze-stock AAPL, /risk-check TSLA, etc.

Available Skills

Each skill orchestrates 5-14 tools in parallel, cross-references the data, and outputs a structured verdict with direction, confidence, and key levels. Skills degrade gracefully when optional API keys are missing.

See skills/README.md for the full catalog, API key requirements, and customization guide.

Development

npm install
npm run build
npm test
npm run lint          # TypeScript type checking
node dist/index.js    # Run locally

Architecture

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

HTTP Sidecar Mode

An optional HTTP server that exposes module client functions over REST. Designed for integrations that need market data without MCP (e.g., trading bots, LLM pipelines).

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

Endpoints include /tradingview/scan, /finnhub/company-news, /sentiment/fear-greed, /options/chain, /fred/indicator, and more. Gated endpoints (Finnhub, FRED) require API keys via environment variables. CORS is restricted to localhost origins.

Rate Limits

All modules use in-memory TTL caching to minimize API calls. Error responses include retry hints for rate-limited requests.

License

MIT