Stock Screener MCP Server

Stock Screener 🇺🇸 🇨🇳 🇭🇰 🇯🇵 🇰🇷 🇹🇼 🇮🇳 🇩🇪 🇨🇦 🇸🇬 🇲🇾 🇦🇺

Technical and fundamental scans, market breadth, group rankings, theme discovery and AI-assisted research

Scan and track US, Hong Kong, India, Japan, Korea, Taiwan, mainland China A-shares, Germany, Canada, Singapore, Malaysia, and Australia markets.

Live app: Daily → Scan → stock detail → Groups → RRG → Stock Matrix · Static site on a phone: Daily → Scan cards → Breadth → RRG

Use it without installing

Read-only daily snapshot running on GitHub Pages: xang1234.github.io/stock-screener

Updated daily after market close.

Plain-HTML pages for every scannable stock, the main screens, group rankings and breadth, in all 12 markets: browse by market.

The forward-return scoreboard shows what happened after stocks newly entered each preset screen, 5, 20 and 60 sessions later, including how often they beat the market's benchmark. Returns are price only, before costs. The record began in October 2026, and thin samples are labeled.

See the Static Site Guide for exactly what works in static mode.

Use it from your terminal

With uv installed, uvx fetches the rest:

uvx stockscreen-mcp screen minervini --market US

Add --tradingview to save every match as a comma-separated file for TradingView's watchlist import, which requires that format. Malaysia and Beijing listings are skipped. See stockscreen-mcp for the other commands.

Ask your AI assistant

The same daily data is available to Claude, Cursor, VS Code or any MCP client through stockscreen-mcp. It needs no API keys and no server:

claude mcp add stockscreen -- uvx stockscreen-mcp

Then ask, for example: "Which US stocks pass the Minervini trend template today, and which are in top-20 industry groups?" It covers screens, RS ratings, market health and breadth, and group rankings for all 12 markets.

Features

• 12-market coverage - exchange calendars, independent data and scans.
• Multiple screening methodologies - Minervini, CANSLIM, IPO, Volume Breakthrough, etc. with composite scoring.
• Market Health and Exposure - Market-regime overlay for position sizing and risk posture.
• Market Breadth - StockBee-style daily movers and trend windows, advance/decline and new-high/new-low health bars, T2108, a benchmark overlay, and a significance heatmap built from one shared calculation layer.
• Industry groups with Relative Rotation Graph - groups ranked by relative strength with movers (1W/1M/3M/6M) and constituent analysis, plus RRG charts plotting RS-Ratio vs RS-Momentum through (Leading → Weakening → Lagging → Improving). The Matrix tab adds Grid and Clusters layouts colored by 1-day, 1-week, 1-month change, or Stock RS.
• Watchlists and Themes - RS and price sparklines, multi-period change bars, drag-and-drop folders, and full-screen chart navigation.
• Theme discovery - AI theme identification from RSS, Twitter/X, and news feeds; tracks trending vs. emerging themes and alerts on momentum shifts.
• AI research chatbot - LLM powered chatbot with optional web search and persistent conversation history.
• Operations - startup data bootstrap, runtime status, and Operations console for queues/jobs/telemetry.
• Options Command Center - opt-in US-only options context for the current top Candidates and Leaders, with focused gamma, volatility, skew, and activity views plus ticker history.
• Backtest - Backtest page that validates published scan picks and theme alerts against price history.

Market Health and Exposure

Scan results table

Group RS: industry rankings, relative-strength statistics, and changes in group rank

RRG: sector rotation with direction-arrowed weekly tails; full 197-group scope available from the same view

Matrix Grid: sector and IBD industry rows, market-cap columns, and individual stock tiles

Matrix Clusters: market-cap-sized bubbles with green centers and red perimeters. Both layouts support 1-day, 1-week, 1-month change, and Stock RS in the live app and static site. See the Group Matrix Guide.

Market Breadth combines advance/decline and new-high/new-low health bars with an SPY overlay and a color-coded history table for primary, secondary, and context indicators.

Options Command Center: switch between Gamma, Volatility, Skew, and Activity views without scanning an entire option universe. See the Options Command Center Guide.

Typical flow: sign in → bootstrap markets → review the Daily dashboard → run a Scan → drill into a stock → monitor Operations → validate outcomes on Backtest. For the full page-by-page tour, see the Live App Guide.

Quickstart (Docker)

Needs Docker and Python 3.11+. One command pulls the published images that match your checkout, writes .env.docker with a generated login password, and waits until every service is healthy:

git clone https://github.com/xang1234/stock-screener.git
cd stock-screener
scripts/quickstart.sh
# Open the printed URL (http://localhost) and log in with the printed password

Add markets or change the port with ENABLED_MARKETS=US,HK FRONTEND_PORT=8080 scripts/quickstart.sh. Re-run it after git pull to upgrade. For the chatbot, add an LLM key such as GROQ_API_KEY to .env.docker and re-run. CI runs this same install against each published main build and release tag, and only creates a GitHub Release once it passes.

On first launch the app opens to a first-run bootstrap screen — no pre-seeded database needed. Pick one primary market for startup defaults and optionally enable more to hydrate in the background, then start. Enabling many markets at once noticeably slows the first run, so start with one and add the rest after the workspace is ready.

• Homelab / VPS / local-dev compose / GHCR options: Docker Deployment
• Building from source: Development Guide
• Bootstrap stages, stale/failure handling, re-runs: Operations Guide

Configuration

Scanning and all core features work with no API keys. The AI chatbot requires at least one LLM provider key.

Optional web-search keys (TAVILY_API_KEY, SERPER_API_KEY) are read by the Hermes assistant sidecar; the backend does not read them. Full reference: Environment Variables.

Application pages

Tech stack

Backend: FastAPI, SQLAlchemy, Alembic, Celery, Redis, PostgreSQL Frontend: React 18, Vite, Material-UI, TanStack Query / Table, Recharts Data: yfinance, Finviz, SEC EDGAR, official X API (optional)

Documentation

Disclaimer

This software is for educational and research purposes only. It is not financial advice. Always do your own research and consult a licensed financial advisor before making investment decisions.

License

Released under the Apache License 2.0.