Skip to main content
Glama
finviz-mcp

finviz-mcp

by baba20o

finviz-cli

Finviz Elite data from the command line, with a local history of trading days and a set of computed columns for studying stocks in play. Built for people at a terminal and for programs and agents reading its output.

This is an independent, unofficial project. It is not affiliated with or endorsed by Finviz. It needs your own Finviz Elite subscription and its API token, and it uses only the export endpoints Finviz documents for Elite subscribers.

finviz screen "abs(gap) <= 3 and open_chg >= 10 and relvol >= 3"
finviz intraday NVDA --days 3

Install

pip install git+https://github.com/baba20o/finviz-cli

Or from a clone, with the test tools:

pip install -e ".[dev]"

Python 3.10 or newer.

Related MCP server: finance-mcp

Token

Your token is shown on the API pages of your Elite account. Put it in a .env file (.env.example is a template):

FINVIZ_API_KEY=your-token

finviz takes the token from the first of these that has one:

  1. FINVIZ_API_KEY in the environment;

  2. a .env file in the folder you run the command from;

  3. a .env file in the data folder (~/.finviz-cli/.env), which works from any folder.

The token goes in the request URL, so it is treated as a secret everywhere: the CLI never writes it to disk, prints it, or puts it in an error message. finviz doctor checks that it works without showing it. Keep your .env out of version control; this repository's .gitignore already leaves it out.

If you keep the token in AWS Secrets Manager instead, set FINVIZ_SECRET_ID to the secret's name, and AWS_REGION if it is not the one in your AWS settings (both in the environment or in the data folder's .env), and install the aws extra, which adds boto3.

Commands

Command

What it does

finviz screen "<filter>"

Any expression over the columns, on today's pull, one saved day (--date) or all of them (--history)

finviz categories

Movers grouped by the outline of their day and what set them off

finviz movers

The day's movers with how each closed: a watchlist for the next session

finviz ticker SYM...

A ticker across the saved days

finviz intraday SYM...

Each recent session from minute bars: premarket high, open, high and low with their times, close, how much of the run was kept, when the premarket high was passed

finviz splits

Reverse splits found in the saved days

finviz snapshot

Pull the screener now and keep it; from five minutes after the close it becomes the day's record

finviz earnings

Earnings calendar; --sync fills the store so saved days get an earnings catalyst

finviz bars SYM --tf i1 --range d5

Price history

finviz options SYM, statements SYM

The options chain; a financial statement, with its currency

finviz news, short-interest, filings, insiders

Headlines, short interest, SEC filings and insider transactions

finviz economic, dividends

The economic and the dividend calendar

finviz groups, futures, forex, crypto

Sector and industry totals; how futures, currencies and coins have moved

finviz managers, funds, holdings ID

Institutional managers and funds, and what one of them holds

finviz export <path> key=value ...

Any export endpoint without its own command

finviz columns

Screener columns: Finviz id, our key, header. --screen lists the columns a filter can name, with their meaning

finviz history status / import-lfr FOLDER

What is saved; bring in end-of-day files saved by a separate collector (only ones named for their own date and captured after the close)

finviz doctor

Token, connection and store check

finviz COMMAND --help describes each one.

Output is a table at a terminal and one JSON object per line when piped. --format table|ndjson|json|csv overrides that. Notes about what was loaded go to stderr, so piped output is only the rows.

A filter is an expression over the column names. Text works too:

finviz screen "yesterday == 'mover, weak close' and float_m < 20" --date 2026-11-09
finviz screen "news.str.contains('Reverse Stock Split')" --history --show date,ticker,price,chg,news

A filter can compare and combine columns, do arithmetic, and call a short list of column methods (abs, isin, between, isna, .str.contains and a few more), and it has to come to true or false for each row. The CLI parses it, checks it and works it out itself; the text is never handed to pandas or to anything else to evaluate. A filter is data, not code, whether a person typed it or a model wrote it.

For agents

The CLI is built to be driven by a language model as much as by a person: stable column names, one JSON object per line, notes kept apart from rows, exit codes that mean something, and errors that say what to fix.

finviz-mcp serves the same commands as tools over the Model Context Protocol:

pip install "finviz-cli[mcp] @ git+https://github.com/baba20o/finviz-cli"
{"mcpServers": {"finviz": {"command": "finviz-mcp"}}}

There are 21 tools, all read-only. Each returns the same shape (ok, rows, row_count, notes, and error or truncated when they apply), caps its rows, and leaves empty fields out. A failure comes back as a result that says why, never as a traceback. Values supplied by the model can never become command switches.

docs/agent-guide.md is the guide written for the model itself: which tool answers which question, how to write a filter, and how to read the numbers without being misled by them.

What it adds to Finviz's columns

  • From one row: dollar volume, float rotation, range, where the price sits in the day's range, how much of a run above the open was kept.

  • Labels for a finished day: how it opened, what it did, how it closed, whether it was a mover, and what set it off (earnings, news, nothing).

  • From earlier saved days: what the name did the session before, how many mover days it had in the last ten sessions, and how long ago its last reverse split was.

  • From minute bars (finviz intraday): the premarket high, the times of the high and the low, and when the premarket high was passed.

The exact rules are in docs/enrichment.md. The labels describe what happened. They are not trading rules, and nothing here is investment advice.

The store

~/.finviz-cli (or $FINVIZ_CLI_HOME) holds one file per trading day, every snapshot, the earnings calendar and a parse cache. That is market data only; the one thing in the folder that can be a secret is a .env you put there yourself. A day taken by this CLI covers every listed stock, including the ones with no float on record; a day brought in with import-lfr covers whatever its collector kept. See docs/quirks.md for what that means in practice.

Commands that need today's data reuse the latest whole-market pull when it is still good: for ten minutes while the session is open, and all evening once it was taken after the close. A morning pull is never used in place of the close. --refresh forces a new one.

Every whole-market pull is checked before it is used (columns, complete rows, row count, unique tickers, prices, coverage against what is already filed, not a repeat of the day before). One that passes on a trading day, five minutes or more after the close (16:05 ET, 13:05 on an early close), is filed as that day's record. One that fails is kept as <time>_rejected.csv, is never shown or filed, and the command says why.

Exit codes: 0 fine, 1 an error, 2 a usage error or a Finviz failure, 3 a pull or an import that was rejected (from any command that met it).

How it treats Finviz's API

  • Finviz allows 10 requests per 5 seconds per account, shared by everything that uses the token. The client paces itself at one request per 0.75 s, across every finviz process on the machine, through a small file in the data folder. After a 429 it waits out the time Finviz asks for.

  • One whole-market request serves every screening command for as long as it is still good, so a session of screening costs a handful of requests, not one per question.

  • Errors are one line with the token taken out of anything in them, and with Finviz's own reason when it gives one (Ticker not found.). FINVIZ_CLI_DEBUG=1 adds a traceback, redacted the same way.

The data belongs to Finviz and its providers. What you may do with it is set by Finviz's terms for your subscription, not by this project's license.

Docs

Development

python -m pytest

Tests use made-up rows and a fake client. None of them touches Finviz, the real store, or your token.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 10 financial data tools (market data, economic indicators, news, insider trades, and calendars) via a single MCP layer, enabling any MCP-compatible LLM to access diverse financial data through a unified interface.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Provides live financial data for any LLM agent, including stock quotes, crypto prices, SEC filings, XBRL financials, FX rates, and macro indicators, through ten MCP tools.
      11
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Institutional financial data for AI agents: credit, private markets, options history, filings.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides MCP tools that let AI agents retrieve stock price data, validate data quality, analyze chart trends and volatility, and fetch news sentiment, enabling structured financial analysis workflows.
      -