stock-scanner-mcp 1.7.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/dist/index.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/config.ts
 function parseConfig(args) {
@@ -26,7 +26,8 @@ function parseConfig(args) {
     enabledModules,
     env: {
       FINNHUB_API_KEY: process.env.FINNHUB_API_KEY,
-      ALPHA_VANTAGE_API_KEY: process.env.ALPHA_VANTAGE_API_KEY
+      ALPHA_VANTAGE_API_KEY: process.env.ALPHA_VANTAGE_API_KEY,
+      FRED_API_KEY: process.env.FRED_API_KEY
     }
   };
 }
@@ -2482,6 +2483,184 @@ function createOptionsCboeModule() {
   };
 }
 
+// src/modules/fred/index.ts
+import { z as z9 } from "zod";
+
+// src/modules/fred/client.ts
+var BASE_URL7 = "https://api.stlouisfed.org/fred";
+var CACHE_TTL7 = 30 * 60 * 1e3;
+var cache7 = new TtlCache(CACHE_TTL7);
+var HIGH_IMPACT_RELEASES = {
+  10: "Consumer Price Index",
+  46: "Producer Price Index",
+  50: "Employment Situation",
+  53: "Gross Domestic Product",
+  54: "Personal Income and Outlays",
+  101: "Federal Funds Rate",
+  7: "Advance Retail Sales",
+  9: "Industrial Production and Capacity Utilization",
+  18: "Housing Starts",
+  32: "ISM Manufacturing"
+};
+var COMMON_SERIES = {
+  fed_funds: "DFF",
+  cpi: "CPIAUCSL",
+  core_cpi: "CPILFESL",
+  ppi: "PPIFIS",
+  gdp: "GDPC1",
+  unemployment: "UNRATE",
+  nonfarm_payrolls: "PAYEMS",
+  treasury_10y: "DGS10",
+  treasury_2y: "DGS2",
+  initial_claims: "ICSA",
+  core_pce: "PCEPILFE"
+};
+function resolveSeriesId(seriesIdOrAlias) {
+  const lower = seriesIdOrAlias.toLowerCase();
+  return COMMON_SERIES[lower] || seriesIdOrAlias.toUpperCase();
+}
+async function getEconomicCalendar(apiKey, limit = 60) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const cacheKey = `calendar:${today}:${limit}`;
+  const cached = cache7.get(cacheKey);
+  if (cached) return cached;
+  const highImpactIds = new Set(Object.keys(HIGH_IMPACT_RELEASES).map(Number));
+  const url = `${BASE_URL7}/releases/dates?api_key=${encodeURIComponent(apiKey)}&file_type=json&realtime_start=${today}&include_release_dates_with_no_data=true&sort_order=asc&limit=${limit}`;
+  const data = await httpGet(url);
+  const filtered = (data.release_dates || []).filter((r) => highImpactIds.has(r.release_id)).map((r) => ({
+    release_id: r.release_id,
+    release_name: r.release_name,
+    date: r.date
+  }));
+  cache7.set(cacheKey, filtered);
+  return filtered;
+}
+async function getIndicator(apiKey, seriesIdOrAlias) {
+  const seriesId = resolveSeriesId(seriesIdOrAlias);
+  const cacheKey = `indicator:${seriesId}`;
+  const cached = cache7.get(cacheKey);
+  if (cached) return cached;
+  const baseParams = `api_key=${encodeURIComponent(apiKey)}&file_type=json`;
+  const seriesUrl = `${BASE_URL7}/series?series_id=${encodeURIComponent(seriesId)}&${baseParams}`;
+  const seriesData = await httpGet(seriesUrl);
+  const s = seriesData.seriess[0];
+  const obsUrl = `${BASE_URL7}/series/observations?series_id=${encodeURIComponent(seriesId)}&${baseParams}&sort_order=desc&limit=1`;
+  const obsData = await httpGet(obsUrl);
+  const obs = obsData.observations[0];
+  const result = {
+    series: {
+      id: s.id,
+      title: s.title,
+      frequency: s.frequency,
+      units: s.units,
+      seasonal_adjustment: s.seasonal_adjustment,
+      last_updated: s.last_updated
+    },
+    latest: {
+      date: obs?.date || "",
+      value: obs?.value === "." ? null : obs?.value || null
+    }
+  };
+  cache7.set(cacheKey, result);
+  return result;
+}
+async function getIndicatorHistory(apiKey, seriesIdOrAlias, startDate, endDate, units = "lin") {
+  const seriesId = resolveSeriesId(seriesIdOrAlias);
+  const cacheKey = `history:${seriesId}:${startDate}:${endDate}:${units}`;
+  const cached = cache7.get(cacheKey);
+  if (cached) return cached;
+  const url = `${BASE_URL7}/series/observations?series_id=${encodeURIComponent(seriesId)}&api_key=${encodeURIComponent(apiKey)}&file_type=json&observation_start=${encodeURIComponent(startDate)}&observation_end=${encodeURIComponent(endDate)}&units=${encodeURIComponent(units)}&sort_order=asc`;
+  const data = await httpGet(url);
+  const result = (data.observations || []).filter((o) => o.value !== ".").map((o) => ({
+    date: o.date,
+    value: o.value
+  }));
+  cache7.set(cacheKey, result);
+  return result;
+}
+async function searchSeries(apiKey, query, limit = 10) {
+  const cacheKey = `search:${query}:${limit}`;
+  const cached = cache7.get(cacheKey);
+  if (cached) return cached;
+  const url = `${BASE_URL7}/series/search?search_text=${encodeURIComponent(query)}&api_key=${encodeURIComponent(apiKey)}&file_type=json&limit=${limit}&order_by=search_rank`;
+  const data = await httpGet(url);
+  const result = (data.seriess || []).map((s) => ({
+    id: s.id,
+    title: s.title,
+    frequency: s.frequency,
+    units: s.units,
+    popularity: s.popularity,
+    last_updated: s.last_updated
+  }));
+  cache7.set(cacheKey, result);
+  return result;
+}
+
+// src/modules/fred/index.ts
+function createFredModule(apiKey) {
+  const metadata2 = { source: "fred", dataDelay: "varies by indicator" };
+  const calendarTool = {
+    name: "fred_economic_calendar",
+    description: "Get upcoming US economic release dates (FOMC, CPI, PPI, NFP, GDP, PCE, jobless claims, retail sales, ISM, treasury rates). Filters to high-impact releases only. Use this to identify macro catalysts that could move markets.",
+    inputSchema: z9.object({
+      limit: z9.number().optional().default(60).describe("Max raw results to fetch before filtering (default: 60)")
+    }),
+    handler: withMetadata(async (params) => {
+      const releases = await getEconomicCalendar(apiKey, params.limit);
+      return successResult(JSON.stringify(releases, null, 2));
+    }, metadata2)
+  };
+  const indicatorTool = {
+    name: "fred_indicator",
+    description: "Get the latest value of a US economic indicator from FRED. Accepts FRED series IDs (e.g. 'CPIAUCSL', 'DFF', 'UNRATE') or common aliases: cpi, core_cpi, ppi, gdp, unemployment, nonfarm_payrolls, fed_funds, treasury_10y, treasury_2y, initial_claims, core_pce. Returns the indicator metadata (title, frequency, units) and latest observation.",
+    inputSchema: z9.object({
+      series_id: z9.string().describe("FRED series ID or alias (e.g. 'cpi', 'UNRATE', 'treasury_10y')")
+    }),
+    handler: withMetadata(async (params) => {
+      const result = await getIndicator(apiKey, params.series_id);
+      return successResult(JSON.stringify(result, null, 2));
+    }, metadata2)
+  };
+  const historyTool = {
+    name: "fred_indicator_history",
+    description: "Get historical values for a US economic indicator from FRED. Accepts same series IDs/aliases as fred_indicator. Supports units transformation: 'lin' (raw level), 'chg' (change), 'pc1' (% change from year ago \u2014 useful for YoY inflation), 'pch' (% change from prior period). Use 'pc1' with CPI/PPI to get YoY inflation rates directly.",
+    inputSchema: z9.object({
+      series_id: z9.string().describe("FRED series ID or alias"),
+      start_date: z9.string().describe("Start date YYYY-MM-DD"),
+      end_date: z9.string().describe("End date YYYY-MM-DD"),
+      units: z9.enum(["lin", "chg", "ch1", "pch", "pc1", "pca"]).optional().default("lin").describe("Units: lin=level, pch=% change, pc1=YoY % change (default: lin)")
+    }),
+    handler: withMetadata(async (params) => {
+      const result = await getIndicatorHistory(
+        apiKey,
+        params.series_id,
+        params.start_date,
+        params.end_date,
+        params.units
+      );
+      return successResult(JSON.stringify(result, null, 2));
+    }, metadata2)
+  };
+  const searchTool = {
+    name: "fred_search",
+    description: "Search FRED for economic data series by keyword. Returns series IDs that can be used with fred_indicator and fred_indicator_history. Results sorted by relevance. Use to discover series IDs for niche indicators.",
+    inputSchema: z9.object({
+      query: z9.string().describe("Search keywords (e.g. 'consumer price index', 'housing starts')"),
+      limit: z9.number().optional().default(10).describe("Max results (default: 10, max: 50)")
+    }),
+    handler: withMetadata(async (params) => {
+      const results = await searchSeries(apiKey, params.query, params.limit);
+      return successResult(JSON.stringify(results, null, 2));
+    }, metadata2)
+  };
+  return {
+    name: "fred",
+    description: "FRED economic data: calendar, indicators, interest rates, inflation",
+    requiredEnvVars: ["FRED_API_KEY"],
+    tools: [calendarTool, indicatorTool, historyTool, searchTool]
+  };
+}
+
 // src/index.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname(__filename);
@@ -2501,6 +2680,9 @@ function buildModules(env) {
   if (env.ALPHA_VANTAGE_API_KEY) {
     modules.push(createAlphaVantageModule(env.ALPHA_VANTAGE_API_KEY));
   }
+  if (env.FRED_API_KEY) {
+    modules.push(createFredModule(env.FRED_API_KEY));
+  }
   return modules;
 }
 function printHelp() {
@@ -2517,15 +2699,16 @@ OPTIONS
   --modules <list>        Comma-separated modules to enable (default: all available)
   --default-exchange <ex> Default exchange for symbol resolution (default: NASDAQ)
 
-MODULES (39 tools total)
-  tradingview        7 tools  Stock scanning, quotes, technicals       (no key)
+MODULES (47 tools total)
+  tradingview        10 tools Stock scanning, quotes, technicals       (no key)
   tradingview-crypto 4 tools  Crypto pair scanning and technicals      (no key)
   sec-edgar          6 tools  SEC filings, insider trades, holdings    (no key)
   coingecko          3 tools  Crypto market data and trending          (no key)
-  options            4 tools  Options chains, Greeks, unusual activity  (no key)
+  options            5 tools  Options chains, Greeks, unusual activity  (no key)
   options-cboe       1 tool   CBOE put/call ratio sentiment            (no key)
   finnhub            9 tools  Quotes, profiles, peers, news, earnings  (FINNHUB_API_KEY)
   alpha-vantage      5 tools  Stock quotes, fundamentals, dividends    (ALPHA_VANTAGE_API_KEY)
+  fred               4 tools  Economic calendar, indicators, rates     (FRED_API_KEY)
 
 SETUP (Claude Code)
   Add to ~/.claude.json or .mcp.json:
@@ -2537,7 +2720,8 @@ SETUP (Claude Code)
         "args": ["-y", "stock-scanner-mcp"],
         "env": {
           "FINNHUB_API_KEY": "your-key",
-          "ALPHA_VANTAGE_API_KEY": "your-key"
+          "ALPHA_VANTAGE_API_KEY": "your-key",
+          "FRED_API_KEY": "your-key"
         }
       }
     }
@@ -2583,7 +2767,7 @@ async function main() {
   server.registerPrompt("analyze_stock", {
     description: "Analyze a stock ticker \u2014 includes crypto correlation check for crypto-related companies",
     argsSchema: {
-      ticker: z9.string().describe("Stock ticker symbol (e.g. AAPL, CIFR, MARA)")
+      ticker: z10.string().describe("Stock ticker symbol (e.g. AAPL, CIFR, MARA)")
     }
   }, async ({ ticker }) => {
     return {
@@ -2617,8 +2801,8 @@ async function main() {
   server.registerPrompt("intraday_candidates", {
     description: "Find intraday trading candidates with custom price range and filters",
     argsSchema: {
-      min_price: z9.string().optional().describe("Minimum stock price (default: 10)"),
-      max_price: z9.string().optional().describe("Maximum stock price (default: 50)")
+      min_price: z10.string().optional().describe("Minimum stock price (default: 10)"),
+      max_price: z10.string().optional().describe("Maximum stock price (default: 50)")
     }
   }, async ({ min_price, max_price }) => {
     const min = min_price || "10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stock-scanner-mcp",
-  "version": "1.7.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",