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:

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:

[email protected]

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
[email protected]

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:

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.