finviz-mcp

Read-only MCP server for finviz.com US market data, with a hard robots.txt compliance guard in front of every request.

14 tools, stdio transport, no API key required. Built for agents that need US fundamentals and market context next to an Indonesian-market data stack.

python finviz_cli.py list                                  # every tool, one line each
python finviz_cli.py quote ticker=AAPL
python finviz_cli.py quote_batch tickers=AAPL,MSFT,JPM preset=valuation
python finviz_cli.py group_performance group=sector

Why it exists

The obvious Finviz tool is the screener — and the docs used to say it was unusable. That was wrong, and the correction is the most useful thing in this repo. Every /screener?... URL does redirect to /screener/stocks?..., which finviz's own robots.txt Disallows for generic clients — so custom filters still require an explicit opt-in. But the allow-listed signal URLs (v=340, v=320, v=210) work, and the "JavaScript-rendered, zero rows" claim was this server's own parsing gap: those pages ship their full result set inside a <script type="application/json"> blob at data.rows[], not as an HTML <table>. Reading that blob yields typed numbers and every row on the page (f=industry_shellcompanies returns all 328 shell companies, 20 per page, with marketCap/price as floats, and v=121/v=161 give valuation and balance-sheet fields). Use screener_signal for the allow-listed signals and custom_screener with allow_noncompliant=True for arbitrary filters. For fundamentals on a list of tickers you already have, quote_batch is still cheaper and fully compliant.

Related MCP server: Finviz MCP Server

Tools (16)

Calendars: dateTo is a lie, weekdays are scanned one by one

Verified 2026-10-31 against all three /api/calendar/* endpoints:

So earnings_calendar / dividends_calendar ask one weekday at a time and economic_calendar walks week-by-week via each week's Friday, then filters to the window requested. Consequences worth knowing:

• A ticker can sit on page 2+ of a busy day (NVO on 2026-11-04 is page 2 of 8). Default is 2 pages/day ≈ 100 rows; raise max_pages_per_day and read counts.rows_truncated_by_page_cap — rows: [] with truncation_is_possible: true means not scanned, not not scheduled.

• counts.coverage_complete says whether every weekday in the range was scanned.

• Saturday/Sunday are never scanned; that is also why the old default window returned nothing every weekend.

• economic_calendar reports weeks_fetched (1..26) so the shape of the walk is visible.

Reading screener rows without a 1e6 error

Free-tier finviz reports marketCap in millions of USD — the raw float is 48499.35 for a $48.5B company. Both screener tools therefore also emit marketCap_usd and a _units legend (marketCap, price, prevClose, change, volume), while leaving the original keys untouched. Measured against quote(): screener 5149206.09 == quote 5149.21B.

screener_all stops on its own rather than trusting the page count: offsets past the end clamp to the last page (r=341/401/981 all return first_row=320 with the same 8 rows) and r>=1001 is HTTP 403, so a naive loop would spend its entire budget re-reading one page. Verified full pull: f=industry_shellcompanies → 17 pages, 328 unique tickers (== totalCount), 0 duplicates, 28.7 s.

quote_batch — the screener replacement

_FUNDA_PRESETS: valuation (P/E, P/S, P/B, P/C, P/FCF, PEG, EV/, Price/), profitability (EPS, ROE, ROA, ROI, Margin, Sales), growth (Growth, EPS this Y, EPS next Y, EPS next 5Y, EPS Q/Q, Sales Q/Q), balance (Debt, Current Ratio, Quick Ratio, Book/sh, Cash/sh), plus all. extra_metrics adds exact labels; include_header adds sector/industry/country per ticker.

Preset matching is by label keyword, not exact string, so a small label drift on Finviz degrades to a missing column instead of a silently empty one. Measured: 3 tickers in 2.8 s at the default 1 s rate limit, 10 columns returned.

quote_batch does not discover tickers. If you do not already know the list, this server cannot help you, and any tool here that pretends otherwise is lying.

Insider trades — filter server-side or lose rows

insider_trades used to filter client-side over whatever the default page held, and that produced silently wrong answers: ticker="NVDA" returned 0 rows (NVDA simply was not in the 200-row global page) while ticker="AAPL" returned 1 of a real 200. The fix pushes every filter into finviz's own query params — t (ticker), tc (transaction type), tv (min value), or (owner type), o (sort).

Query-param semantics, all verified on 2026-10-30:

Coverage ceiling. The page is one table of at most 200 rows and ignores pagination — p=1, p=2, p=3 and r=201 all return the identical 200 rows (byte-identical hash). So only the newest ~200 matching rows exist. The tool reports this instead of hiding it: coverage.page_rows_total, rows_matching_filters, truncated_by_limit, page_is_full, and window.{newest,oldest_on_page}. Sorting by value reaches far older rows (t=NVDA&o=-transactionValue spans 2017→2026) than sorting by date (2025→2026) — the 200-row cut is by sort order, so a "latest transactions" query genuinely only sees recent history for busy tickers.

An empty result for a ticker now distinguishes the two causes: the tool probes /stock?t= and reports coverage.ticker_exists — a typo returns ticker_exists: false, a real ticker with no matching rows returns true.

Calendar pagination

The internal JSON APIs return 50 rows per page and ignore pageSize (verified). _calendar_collect() merges up to 3 pages (150 rows) before applying filters, because row-level filters over a single page silently miss matches on later pages. Verified effect: min_yield=8 on dividends went from 4 rows to 22. Page counts are reported back as counts.pages_fetched and counts.raw_items_considered.

Known-unavailable endpoints — do not re-probe

• /api/quote responds but always returns 400 {"error":"invalid quote query"} for 16 parameter shapes tried.

• /map.ashx (heatmap) renders via a JS bundle; the data is not in the HTML.

• /etf, /earnings, /insider (without .ashx) → 404.

Unexplained behaviour

A wider date range can return fewer rows (1–30 Sep → 17 items; 8–11 Sep → 18 items). The endpoint appears to window or offset results itself. Date ranges are not fully deterministic — do not build anything that depends on strict monotonicity.

Compliance model

robots.txt is fetched live (cached 24 h) and evaluated with a correct longest-match matcher (* wildcard, $ anchor, Allow wins ties). Every request is checked before sending and again against the final URL after redirects — that second check is what catches the /screener?* → /screener/stocks?* trap.

Verified policy map:

screener_signal runs without any override for the allow-listed signals — an earlier version hardcoded v=111 and so denied itself; if a signal URL is not Allow-listed it still refuses. custom_screener needs allow_noncompliant=True because arbitrary f= filters 302-redirect into /screener/stocks?*; the response is then flagged robots_compliant: false. FINVIZ_ALLOW_NONCOMPLIANT=1 flips the default globally; that is your call to make, not this server's.

Three stdlib robots.txt traps this server works around

Do not "simplify" this code away:

1. RobotFileParser stores User-agent: * rules in rp.default_entry, not in rp.entries. Reading only entries silently allows every request.

2. RuleLine.path is percent-quoted, so /screener?* is stored as /screener%3F%2A; it must be unquote()d before matching or the rule never fires.

3. Python's built-in can_fetch treats * literally, so it also gets /screener?* wrong. This server does its own longest-match evaluation.

Install

python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

Register with Hermes (or any MCP client that speaks stdio):

mcp_servers:
  finviz:
    command: /path/to/.venv/bin/python
    args: ["/path/to/finviz_mcp_server.py"]
    trust: full
    timeout: 120
    env:
      FINVIZ_MIN_INTERVAL: "1.0"
      FINVIZ_CACHE_TTL: "60"

No env block is required — every variable has a default. The server never reads secrets, because it has none.

Usage

Via an MCP client: finviz_quote(ticker="AAPL"), finviz_economic_calendar(min_importance=3).

Without a gateway restart, use the CLI (it speaks JSON-RPC over stdio to the same server):

python finviz_cli.py list
python finviz_cli.py quote ticker=AAPL
python finviz_cli.py quote_batch tickers=AAPL,MSFT,JPM preset=all
python finviz_cli.py group_performance group=industry
python finviz_cli.py economic_calendar min_importance=3
python finviz_cli.py screener_signal signal=topgainers allow_noncompliant=true

Argument coercion follows the tool's declared schema, not punctuation: tickers=AAPL,MSFT becomes an array because the parameter is list[str], while filters=fa_div_o6,fa_pe_u20 stays one string because the parameter is str. Getting this wrong is the most common way to break the CLI, so it is handled centrally in coerce_typed().

Runtime test scripts

They locate the server and interpreter relative to themselves (HERE), and accept overrides: FINVIZ_PY, FINVIZ_SERVER, FINVIZ_ENV_FILE, FINVIZ_STDERR_LOG. FINVIZ_ENV_FILE is optional — without it they inherit os.environ, so they work outside any agent framework.

Tuning

Limitations / risks

• US markets only. No IDX coverage; use a separate source for Indonesian data.

• Free tier is delayed, not real-time. Real-time + export is Finviz Elite.

• Finviz is migrating to React-rendered pages (v=340). Expect breakage on their next view change.

• Scraping at volume risks IP blocks. The 1 s limiter is deliberate.

• Data is external and unverified: label outputs partially verified, never authoritative.

• quote_batch costs one request per ticker at 1 s each — 40 tickers is ~40 s. Batch size is capped for that reason, not by an API limit.

• Calendar date ranges are not fully deterministic (see above).

License

MIT — see LICENSE. Not affiliated with Finviz.

Educational/analytical use only. Not investment advice.