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 --versionIf 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-remoteStep 3: Configure Environment
Copy the example env file and add your email (required by the SEC for EDGAR API access):
cp .env.example .envEdit .env and set your contact email:
SEC_EMAIL=your-email@example.comStep 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.comLocal Remote Run
finviz-sec-mcp-remoteThis 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.
