Finviz + SEC EDGAR MCP Server

A free MCP server for stock research using Finviz screening and SEC EDGAR filings. No paid subscriptions required.

Works with any MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Zed, and more.

https://financial-research-finviz-sec-mcp.onrender.com/mcp

Collaboration Preference

This project is released under the MIT license. If you build on it, I would highly prefer and appreciate active collaboration.

This is a request about how I would like collaboration to happen, not an additional license restriction.

What You Get

24 tools accessible conversationally through any MCP client:

Tool	What it does
screen_stocks	Full Finviz screener with 67+ filters: P/E, ROE, margins, debt ratios, etc.
screen_value_stocks	Quick value screen with sensible defaults
screen_from_url	Paste any finviz.com screener URL and run it
list_filter_options	Discover all available filter codes
get_stock_fundamentals	90+ data points for any ticker
compare_stocks	Side-by-side fundamental comparison
get_sec_filings	List recent SEC filings (10-K, 10-Q, 8-K, etc.)
get_filing_text	Read clean text of SEC filings (iXBRL properly stripped)
get_financial_history	Historical revenue, net income, EPS from XBRL data
get_per_share_fundamentals	Historical per-share valuation inputs from SEC XBRL filings
get_financial_snapshot	Full income statement, balance sheet & cash flow from latest filing
get_financial_ttm	Trailing twelve months for one or more companies
compare_financials	Compare a metric across multiple companies for a given year
get_insider_filings	SEC Form 3/4/5 insider filings with structured trade data
compare_sectors	Sector-level comparison
compare_industries	Industry aggregate comparison
stock_vs_industry	Compare one stock against its industry aggregates
screen_industry	Filter within a specific industry
get_analyst_ratings	Analyst price targets and ratings
get_insider_activity	Insider buy/sell activity
get_stock_news	Recent news headlines
get_earnings_news	Earnings-related and transcript-related headlines
get_annual_price_history	Annual high, low, and average close price history from Yahoo Finance
get_inputs_tab_data	Consolidated extraction package for CWC specific valuation workbook

Data Sources

• Finviz (free tier): Screener, fundamentals, news, insiders, analyst data. Delayed 15–20 min (irrelevant for value research).
• SEC EDGAR (free, public): 10-K/10-Q/8-K filings, XBRL financial data, insider forms. No API key needed.

---

Setup Guide (macOS / Linux / Windows)

Step 1: Prerequisites

You need Python 3.10+ and pip. Check with:

python3 --version   # Should be 3.10 or higher
pip3 --version

If you don't have Python 3.10+, install it from python.org.

Step 2: Fork, Clone & Install

Preferred workflow: fork this repository on GitHub first, then clone your fork so improvements can flow back cleanly.

git clone https://github.com/YOUR_USERNAME/finviz-sec-mcp.git
cd finviz-sec-mcp

# Create a virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate          # Windows

# Install the package
pip install -e .

For the remote server entrypoint, the package also installs:

finviz-sec-mcp-remote

Step 3: Configure Environment

Copy the example env file and add your email (required by the SEC for EDGAR API access):

cp .env.example .env

Edit .env and set your contact email:

SEC_EMAIL=your-email@example.com

Step 4: Test It Works

# Quick test — should print the current tool count
python -c "
from finviz_sec_mcp.server import server
print(f'{len(server._tool_manager._tools)} tools registered')
"

# Full test — runs a live value screen
python -c "
from finviz_sec_mcp.clients.finviz_client import FinvizClient
results = FinvizClient.screen(
    filters=['cap_largeover', 'fa_pe_u20', 'fa_roe_o15'],
    table='Valuation',
)
print(f'Found {len(results)} value stocks')
for s in results[:3]:
    print(f'  {s[\"Ticker\"]} — P/E: {s.get(\"P/E\")}')
"

Step 5: Configure Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following (replace /path/to/ with your actual path):

{
  "mcpServers": {
    "finviz-sec": {
      "command": "/path/to/finviz-sec-mcp/venv/bin/finviz-sec-mcp"
    }
  }
}

Finding your actual path:

# Run this in the project folder to get the exact paths
echo "\"command\": \"$(pwd)/venv/bin/finviz-sec-mcp\""

Step 6: Restart Claude Desktop

Quit and reopen Claude Desktop. You should see a hammer icon (🔨) in the chat input area. Click it to see all 24 tools.

---

Remote Server Deployment

This repo can also run as a public remote MCP over FastMCP streamable HTTP. That is the preferred setup for org-wide use because the production service can deploy from GitHub main and users no longer need .mcpb uploads.

Remote Environment

Set the remote variables from .env.example:

MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_STREAMABLE_HTTP_PATH=/mcp
SEC_EMAIL=your-email@example.com

Local Remote Run

finviz-sec-mcp-remote

This exposes:

• /mcp
• /healthz

Render Deployment

This repo includes a starter render.yaml that:

• deploys the web service from GitHub
• runs finviz-sec-mcp-remote
• health-checks /healthz

To keep production tied to GitHub main, configure the Render production service to deploy only from the main branch. Unpushed local changes will not affect the live server.

This public remote deployment does not require OAuth or a backing database. Anyone with the deployed /mcp URL can connect, so put rate limiting or basic WAF rules in front of it if you expect outside traffic.

---

Screener Table Views

The screen_stocks tool accepts a table parameter that controls which columns are returned. Each view shows different metrics:

View	Columns Returned
Overview	Company, Sector, Industry, Market Cap, P/E, Price, Change, Volume
Valuation	Market Cap, P/E, Fwd P/E, PEG, P/S, P/B, P/C, P/FCF, EPS This Y, EPS Next Y, EPS Past 5Y, EPS Next 5Y, Sales Past 5Y, Price, Change, Volume
Financial	Market Cap, Dividend, ROA, ROE, ROI, Current Ratio, Quick Ratio, LTDebt/Eq, Debt/Eq, Gross Margin, Oper Margin, Profit Margin, Earnings, Price, Change, Volume
Ownership	Market Cap, Outstanding, Float, Insider Own, Insider Trans, Inst Own, Inst Trans, Float Short, Short Ratio, Avg Volume, Price, Change, Volume
Performance	Perf Week, Perf Month, Perf Quart, Perf Half, Perf Year, Perf YTD, Volatility W, Volatility M, Recom, Avg Volume, Rel Volume, Price, Change, Volume
Technical	Beta, ATR, SMA20, SMA50, SMA200, 52W High, 52W Low, RSI, Price, Change, Volume

Default is Valuation. You can run the same screen with different views to get a fuller picture of the results.

---

Example Prompts

Once set up, you can just talk naturally:

"Find me undervalued large-cap stocks with strong margins and low debt"

"Compare AAPL, MSFT, and GOOGL on valuation and profitability metrics"

"Show me the most recent 10-K filing for Berkshire Hathaway"

"What's the historical revenue trend for NVDA from SEC filings?"

"Screen for dividend stocks with yield over 3%, payout under 60%, and ROE over 15%"

"Show me all consumer defensive stocks with P/E under 20"

"What are the latest insider trades for AAPL?"

"Get analyst price targets for META"

---

Troubleshooting

"No module named 'finviz'" → Make sure you activated the venv and ran pip install -e .

No module named 'src' or stale value-investor-mcp paths → You renamed the project but are still using an old editable install or old Claude config. Recreate the venv, reinstall with pip install -e ., and point Claude Desktop at venv/bin/finviz-sec-mcp.

Screener returns empty → Some filter combinations are too restrictive. Try list_filter_options to check valid codes.

SEC EDGAR rate limit → The client auto-throttles to 10 req/sec. If you hit issues, wait a few seconds.

Claude Desktop doesn't show the tools → Double-check the path in claude_desktop_config.json. The command should point to venv/bin/finviz-sec-mcp inside this project, not your system Python.

License

MIT. See LICENSE.