stock-scanner-mcp 1.8.0 → 1.9.0

package/README.md

@@ -6,6 +6,10 @@
 
 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.
 
+**47 tools** across **9 modules** — 6 modules work with zero API keys.
+
+**[Wiki](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki)** — Full tool reference, example prompts, advanced strategies, and troubleshooting guide.
+
 ## Quick Start
 
 ```bash
@@ -34,7 +38,7 @@ Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):
 }
 ```
 
-### With API keys (optional, enables more tools):
+### With API keys (optional, enables all 47 tools):
 
 ```json
 {
@@ -44,7 +48,8 @@ Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):
       "args": ["-y", "stock-scanner-mcp"],
       "env": {
         "FINNHUB_API_KEY": "your-key-here",
-        "ALPHA_VANTAGE_API_KEY": "your-key-here"
+        "ALPHA_VANTAGE_API_KEY": "your-key-here",
+        "FRED_API_KEY": "your-key-here"
       }
     }
   }
@@ -55,28 +60,33 @@ Add to your Claude Code MCP config (`~/.claude.json` or project `.mcp.json`):
 
 | Module | Tools | API Key | Description |
 |--------|-------|---------|-------------|
-| tradingview | 7 | None | US stock scanner with real-time quotes, technicals, and screening |
+| tradingview | 10 | None | US stock scanner with quotes, technicals, sectors, indices, and screening |
 | tradingview-crypto | 4 | None | Crypto pair scanner with technicals and screening |
 | sec-edgar | 6 | None | SEC filings, insider trades, institutional holdings, ownership |
 | coingecko | 3 | None | Crypto market data, trending coins, global stats |
-| options | 4 | None | Options chains, Greeks, unusual activity, max pain |
+| options | 5 | None | Options chains, Greeks, unusual activity, max pain, implied move |
 | options-cboe | 1 | None | CBOE put/call ratio sentiment indicator |
-| finnhub | 5 | `FINNHUB_API_KEY` | News, earnings, short interest, economic calendar |
+| finnhub | 9 | `FINNHUB_API_KEY` | Quotes, news, earnings, analyst ratings, short interest |
 | alpha-vantage | 5 | `ALPHA_VANTAGE_API_KEY` | Quotes, daily prices, fundamentals, earnings, dividends |
+| fred | 4 | `FRED_API_KEY` | Economic calendar, indicators (CPI, GDP, rates), historical data |
+
 Modules auto-enable when their required environment variables are set. Modules with no required key are always enabled.
 
-## Available Tools (35 total)
+## Available Tools (47 total)
 
 ### TradingView — Stock Scanning (no API key)
 
 | Tool | Description |
 |------|-------------|
 | `tradingview_scan` | Scan US stocks with custom filters (price, RSI, volume, etc.) |
-| `tradingview_quote` | Real-time quotes for stock tickers |
+| `tradingview_compare_stocks` | Side-by-side comparison of 2-5 stocks |
+| `tradingview_quote` | 15-min delayed quotes for stock tickers (includes pre/post-market) |
 | `tradingview_technicals` | Technical indicators (RSI, MACD, moving averages, pivots) |
 | `tradingview_top_gainers` | Today's top gaining stocks by % change |
 | `tradingview_top_losers` | Today's top losing stocks by % change |
 | `tradingview_top_volume` | Highest volume stocks today |
+| `tradingview_market_indices` | Real-time VIX, S&P 500, NASDAQ, Dow Jones |
+| `tradingview_sector_performance` | S&P 500 sector ETF performance (weekly, monthly, YTD) |
 | `tradingview_volume_breakout` | Stocks with unusual volume (2x+ their 10-day average) |
 
 ### TradingView — Crypto (no API key)
@@ -115,6 +125,7 @@ Modules auto-enable when their required environment variables are set. Modules w
 | `options_chain` | Full options chain with Greeks for a given expiration |
 | `options_unusual_activity` | Unusual options activity — high volume/OI contracts |
 | `options_max_pain` | Max pain (strike where most options expire worthless) |
+| `options_implied_move` | Expected move from ATM straddle pricing |
 
 ### Options CBOE — Put/Call Sentiment (no API key)
 
@@ -126,11 +137,15 @@ Modules auto-enable when their required environment variables are set. Modules w
 
 | Tool | Description |
 |------|-------------|
+| `finnhub_quote` | Real-time stock quote |
+| `finnhub_company_profile` | Company info (industry, market cap, IPO date, website) |
+| `finnhub_peers` | Comparable companies in the same industry |
+| `finnhub_market_status` | Exchange open/closed status and current session |
 | `finnhub_market_news` | Latest market news (general, forex, crypto, merger) |
 | `finnhub_company_news` | Company-specific news by ticker and date range |
 | `finnhub_earnings_calendar` | Upcoming and historical earnings reports |
+| `finnhub_analyst_ratings` | Analyst consensus and rating history |
 | `finnhub_short_interest` | Short interest, short ratio, and key financial metrics |
-| `finnhub_economic_calendar` | Economic events (FOMC, CPI, GDP, NFP) with impact ratings |
 
 ### Alpha Vantage — Fundamentals & History (requires `ALPHA_VANTAGE_API_KEY`)
 
@@ -142,6 +157,15 @@ Modules auto-enable when their required environment variables are set. Modules w
 | `alphavantage_earnings_history` | Historical EPS actual vs estimate by quarter |
 | `alphavantage_dividend_history` | Historical dividend payments and dates |
 
+### FRED — US Economic Data (requires `FRED_API_KEY`)
+
+| Tool | Description |
+|------|-------------|
+| `fred_economic_calendar` | Upcoming high-impact economic releases (FOMC, CPI, NFP, GDP) |
+| `fred_indicator` | Latest value for any indicator (CPI, fed funds, unemployment, etc.) |
+| `fred_indicator_history` | Historical values with unit transforms (YoY %, change, level) |
+| `fred_search` | Discover FRED series IDs by keyword |
+
 ## Configuration
 
 ### Environment Variables
@@ -150,6 +174,7 @@ Modules auto-enable when their required environment variables are set. Modules w
 |----------|----------|-------------|
 | `FINNHUB_API_KEY` | No | Enables Finnhub module ([get free key](https://finnhub.io/)) |
 | `ALPHA_VANTAGE_API_KEY` | No | Enables Alpha Vantage module ([get free key](https://www.alphavantage.co/support/#api-key)) |
+| `FRED_API_KEY` | No | Enables FRED module ([get free key](https://fred.stlouisfed.org/docs/api/api_key.html)) |
 
 ### CLI Options
 
@@ -178,7 +203,8 @@ Once configured, just ask Claude naturally:
 - "What's trending in crypto right now?"
 - "Find stocks with unusual volume today"
 - "What earnings are coming up this week?"
-- "Show me the economic calendar for high-impact US events"
+- "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?"
@@ -204,14 +230,15 @@ src/
 ├── config.ts             # CLI arg parsing
 ├── registry.ts           # Module auto-discovery and filtering
 ├── modules/
-│   ├── tradingview/      # 7 tools — stock scanning, quotes, technicals
+│   ├── 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/          # 4 tools — options chains, Greeks, unusual activity
+│   ├── options/          # 5 tools — options chains, Greeks, unusual activity, implied move
 │   ├── options-cboe/     # 1 tool  — CBOE put/call ratio sentiment
-│   ├── finnhub/          # 5 tools — news, earnings, economic calendar
-│   └── alpha-vantage/    # 5 tools — quotes, fundamentals, dividends
+│   ├── 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
 └── shared/
     ├── http.ts           # HTTP client with timeouts and key sanitization
     ├── cache.ts          # In-memory TTL cache
@@ -231,6 +258,7 @@ src/
 | CBOE CDN | No documented limit | 30 min |
 | Finnhub | 30 calls/second | 5 min |
 | Alpha Vantage | 5 calls/minute, 25 calls/day | 1 min |
+| FRED | No hard limit | 30 min |
 
 All modules use in-memory TTL caching to minimize API calls. Error responses include retry hints for rate-limited requests.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stock-scanner-mcp",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "MCP server providing Claude Code with real-time stock and crypto market data, SEC filings, insider trades, and technical analysis",
   "type": "module",
   "bin": {
@@ -28,7 +28,23 @@
     "market-data",
     "claude-code",
     "claude",
-    "ai-tools"
+    "ai-tools",
+    "price-action",
+    "stock-analysis",
+    "technical-analysis",
+    "fundamental-analysis",
+    "options",
+    "options-chain",
+    "economic-data",
+    "fred",
+    "finnhub",
+    "alpha-vantage",
+    "coingecko",
+    "trading",
+    "investing",
+    "financial-data",
+    "stock-scanner",
+    "stock-screener"
   ],
   "author": "Yordan Yordanov",
   "license": "MIT",