stock-scanner-mcp

A modular MCP server for Claude Code and Claude Desktop that provides real-time access to stock and crypto market data. Scan markets, check technicals, monitor insider trades, track earnings, analyze options flow, and optionally save your own watchlists and thesis notes from one server.

69 tools across 15 modules — 11 modules work with zero API keys, including an optional stateful Market Workspace.

Quick Start

Three steps to get the full experience: server config, trading skills, and workspace setup.

Step 1 — Add the server to your MCP config

Copy this complete config block into your config file:

• Claude Code: `~/.claude.json` (global) or `.mcp.json` (project-local)
• Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

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

This gives you 49 tools immediately with no API keys. API keys are optional and free — they unlock 20 additional tools for real-time quotes, news, earnings, and economic data. See API Keys below for where to get them.

> Minimal config — if you don't want workspace or API keys, use this instead:

> ```json

> {

> "mcpServers": {

> "stock-scanner": {

> "command": "npx",

> "args": ["-y", "stock-scanner-mcp"]

> }

> }

> }

> ```

> This gives you 42 stateless tools with no local data storage.

Restart Claude Desktop after saving. Claude Code picks up the config automatically.

> Claude Code shortcut — install as a plugin instead of Steps 1 and 2. If you use Claude Code, skip the manual config above and install everything with two commands:

> ```

> /plugin marketplace add yyordanov-tradu/stock-scanner-mcp

> /plugin install stock-scanner@tradu-marketplace

> ```

> Run `/reload-plugins`, then `/mcp` — you should see the `stock-scanner` server listed as connected. The first launch runs `npx -y stock-scanner-mcp`, which downloads the package once (then it is cached). The plugin enables the workspace by default (data is stored in `~/.stock-scanner-mcp`) and passes the optional API keys (`FINNHUB_API_KEY`, `ALPHA_VANTAGE_API_KEY`, `FRED_API_KEY`) through from your environment; modules without a key are skipped automatically.

>

> The plugin already bundles the skills — do NOT run Step 2. All 19 skills ship with the plugin and load under the `stock-scanner:` namespace, e.g. `/stock-scanner:analyze-stock AAPL`, `/stock-scanner:morning-briefing`, `/stock-scanner:setup-market-workspace`. Running the Step 2 installer as well copies a second, unprefixed set into `~/.claude/skills/`, and the two collide — Step 2 is only for the manual (non-plugin) install. After installing, go straight to Step 3, using the namespaced command: `/stock-scanner:setup-market-workspace`.

Step 2 — Install the trading skills

> Skip this step if you installed via the plugin above — the plugin already bundles these skills (as `stock-scanner:`). This step is only for the manual config in Step 1.

Run this command in your terminal:

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

This installs 19 slash commands (like `/morning-briefing`, `/analyze-stock AAPL`, `/setup-market-workspace`) into `~/.claude/skills/` so they're available in every Claude Code session. See Trading Skills for the full list.

Step 3 — Set up your workspace

Run `/setup-market-workspace` in Claude Code. It asks three quick questions:

> /setup-market-workspace

Setting up your market workspace — I'll ask a few quick questions to get started...

1. What kind of trader or investor are you?
   (e.g., options trader, swing trader, long-term investor, crypto-focused)

   → "I'm mostly a swing trader, also watch crypto"

2. Which names or assets should I save to your core watchlist?
   (e.g., AAPL, MARA, BTC, Gold)

   → "MARA, HOOD, SOFI, BTC, ETH"

3. Do you want a daily or weekly market review?

   → "Daily"

Once answered, it saves your profile and creates a `core` watchlist:

✓ Workspace saved

  Profile     swing trader | daily review
  Watchlist   core — MARA, HOOD, SOFI, BTC, ETH

You can also skip the skill and ask Claude directly: *"Set up my workspace — I'm a swing trader, create a core watchlist with MARA, HOOD, BTC, daily reviews."*

That's it. You now have 69 tools, 19 skills, and a personalized workspace. Try `/workspace-morning-brief` for your first tailored market scan.

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"
"Set up a core watchlist with MARA, HOOD, and BTC"
"Give me a personalized morning brief for my saved watchlist"

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
• Market Workspace — save a trading profile, named watchlists, and thesis notes for personalized workflows across sessions

Trading Skills

19 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.

Skills degrade gracefully when optional API keys are missing. Workspace skills require `--enable-workspace` in the server config.

Install options

npx -p stock-scanner-mcp stock-scanner-install-skills                    # all 19 skills
npx -p stock-scanner-mcp stock-scanner-install-skills --scope project    # project only (.claude/skills/)
npx -p stock-scanner-mcp stock-scanner-install-skills --category macro   # one category
npx -p stock-scanner-mcp stock-scanner-install-skills --category workspace # workspace skills only
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/`

See skills/README.md for the full catalog.

Market Workspace

The Market Workspace is an optional stateful layer that remembers your trading context across sessions — your trading style, named watchlists, and investment thesis notes per symbol. Skills like `/workspace-morning-brief` use this context to deliver personalized market scans instead of generic ones.

What you can do with it

• `/workspace-morning-brief` — personalized pre-market scan that reads your profile and watchlist, checks earnings, news, and price action for your names, and highlights what matters today
• Add more watchlists — ask Claude: *"Create a watchlist called 'earnings' with AAPL, MSFT, GOOG"*
• Track investment theses — save your reasoning per ticker so the system monitors it for you (see below)
• Update anytime — *"Add NVDA to my core watchlist"* or *"Change my review cadence to weekly"*

Thesis Tracking

Save your investment reasoning per ticker — direction, key levels, catalysts, and timeframe — so the system can monitor it across sessions.

Save a thesis:

"My thesis on NIO: bullish above $6.35, that confirms the uptrend. Below it the setup is invalid."

Claude saves the structured thesis:

How it works in practice: When you run `/workspace-morning-brief`, the brief cross-references your saved theses against live price action:

• NIO drops to $6.10 → *"NIO broke below your $6.35 thesis floor — re-evaluate."*
• NIO rallies to $7.20 → *"NIO holding above your $6.35 level — uptrend thesis intact."*

Without a thesis, the brief just reports a price change. With a thesis, it tells you whether the move matters to your plan.

Each thesis supports five fields: `summary`, `bullCase`, `bearCase`, `catalyst`, and `timeframe`. You can save up to 200 theses per workspace.

Configuration reference

Data is stored locally in `workspace.json` — no cloud sync, no external calls. If you omit `--enable-workspace`, the server stays fully stateless and writes no local data.

For the full list of workspace tools, see the tool reference below.

Documentation

• **Installation & Setup** — Getting the MCP server running in Claude Code or Cursor
• **Trading Skills** — Ready-made workflows for professional analysis
• **Sidecar HTTP API** — REST endpoints for non-MCP clients
• **Docker Deployment** — Running in containers with workspace persistence
• **FAQ & Troubleshooting** — Common issues and solutions

Modules

Modules auto-enable when their API key is set. No-key modules are always enabled, except `workspace`, which requires `--enable-workspace`.

For a complete list of every tool with descriptions, see the Full Tool Reference below.

Full Tool Reference (69 tools)

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)

Sentiment — Fear & Greed (no API key)

Frankfurter — Forex Rates (no API key)

Reddit — Trending Tickers & Sentiment (no API key)

Market Breadth — Breadth Indicators (no API key)

Unified Market — Smart Routing (no API key)

Workspace — Personalized Context (optional, no API key)

Enabled only when you start the server with `--enable-workspace`.

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`)

Configuration

CLI Options

npx -y stock-scanner-mcp --modules tradingview,sec-edgar    # Enable specific modules only
npx -y stock-scanner-mcp --default-exchange NYSE             # Set default exchange
npx -y stock-scanner-mcp --enable-workspace                  # Turn on local workspace tools
npx -y stock-scanner-mcp --enable-workspace --data-dir /tmp/market-workspace  # Custom data directory
npx -y stock-scanner-mcp --help                              # Show all options

API Keys (optional)

All three keys are free — no credit card required:

Add them to the `env` block in your MCP config (see Quick Start).

Use with other MCP clients

Any MCP client that supports stdio servers can run this package. Use the same JSON config from Quick Start. If your client does not expose `npx`, install the package first and point the client at the installed binary instead.

HTTP Sidecar

An optional HTTP server exposing all tools as REST endpoints for non-MCP integrations (GPT Actions, chat UIs, LLM pipelines). It includes an OpenAPI 3.1 specification for automated tool discovery.

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

# Optional: Enable the stateful Market Workspace via HTTP
npx stock-scanner-sidecar --enable-workspace --data-dir ./my-data

# Access the OpenAPI spec
curl http://localhost:3200/openapi.json

See Sidecar HTTP API for endpoint details.

69 tools exposed as REST routes, including `/market/quote`, `/options/chain`, `/workspace/profile`, and more.

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
npm run validate-doc-tools # Skill/command tool reference check

Credibility Artifacts

• Benchmark examples
• Sample transcripts
• Latency & reliability snapshot

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
│   ├── workspace/        # 7 tools — stateful profile, watchlists, thesis notes
│   ├── 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)
│   ├── reddit/           # 4 tools — trending tickers, mentions, sentiment, watchlist scan from Reddit
│   └── unified-market/   # 3 tools — smart provider routing for quotes/profiles/technicals
├── sidecar/
│   ├── index.ts          # HTTP sidecar entry point (port 3200)
│   ├── routes.ts         # Declarative URL routing table
│   └── server.ts         # Dynamic HTTP request handler
└── 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