Finviz MCP Server

A Model Context Protocol (MCP) server that provides comprehensive stock screening and fundamental analysis capabilities using Finviz data.

- Earnings Screener: Find stocks with upcoming earnings announcements
- Volume Surge Screener: Detect stocks with unusual volume and price movements
- Trend Analysis: Identify uptrend and momentum stocks
- Dividend Growth Screener: Find dividend-paying stocks with growth potential
- ETF Screener: Screen exchange-traded funds
- Premarket/Afterhours Earnings: Track earnings reactions in extended hours

- Individual stock fundamental data retrieval
- Multiple stock comparison
- Sector and industry performance analysis
- News and sentiment tracking

- RSI, Beta, and volatility metrics
- Moving average analysis (SMA 20/50/200)

- NEW:get_moving_average_position– see how far price sits above/below the 20-, 50-, and 200-day SMAs in a single call
- SEC Filing List Retrieval

# All AAPL filings (past 30 days) finviz_get_sec_filings(ticker="AAPL", days_back=30) # Major forms only (10-K, 10-Q, 8-K, etc.) finviz_get_major_sec_filings(ticker="AAPL", days_back=90) # Insider trading related (Form 3, 4, 5, etc.) finviz_get_insider_sec_filings(ticker="AAPL", days_back=30)

- Python 3.11 or higher
- Finviz Elite Subscription(required for full functionality)
- Finviz API key (optional but recommended for higher rate limits)

Important: This MCP server requires a Finviz Elite subscription to access comprehensive screening and data features. For more details about Finviz Elite and subscription options, visit:https://elite.finviz.com/elite.ashx

# Clone the repository git clone <repository-url> cd finviz-mcp-server # Create virtual environment with Python 3.11 python3.11 -m venv venv # Activate virtual environment source venv/bin/activate # On macOS/Linux # or venv\\Scripts\\activate # On Windows # Install the package in development mode pip install -e .

# Copy the example environment file cp .env.example .env # Edit .env file and add your Finviz API key FINVIZ_API_KEY=your_actual_api_key_here

# Test if the server starts correctly (press Ctrl+C to stop) finviz-mcp-server # You should see the server starting in stdio mode

# Make sure virtual environment is activated source venv/bin/activate # Run the server finviz-mcp-server

{ "mcpServers": { "finviz": { "command": "/path/to/your/project/venv/bin/finviz-mcp-server", "args": [], "cwd": "/path/to/your/project/finviz-mcp-server", "env": { "FINVIZ_API_KEY": "your_api_key_here", "LOG_LEVEL": "INFO", "RATE_LIMIT_REQUESTS_PER_MINUTE": "100" } } } }

- Replace/path/to/your/project/with your actual project path
- Use the absolute path to thefinviz-mcp-serverexecutable in your virtual environment
- Set thecwd(current working directory) to your project root
- Replaceyour_api_key_herewith your actual Finviz API key

Alternative: Using .env fileIf you prefer to use a.envfile (recommended for security):

{ "mcpServers": { "finviz": { "command": "/path/to/your/project/venv/bin/finviz-mcp-server", "args": [], "cwd": "/path/to/your/project/finviz-mcp-server" } } }

Make sure your.envfile contains all required environment variables.

Build and run the server in a Docker container with SSE transport:

# Build the image docker build -t finviz-mcp-server . # Local-only Docker exposure (recommended): bind localhost on the host # while letting the container listen on all interfaces internally. docker run -d -p 127.0.0.1:8000:8000 \ -e MCP_TRANSPORT=sse \ -e MCP_HOST=0.0.0.0 \ -e MCP_PORT=8000 \ -e FINVIZ_API_KEY=your_key \ finviz-mcp-server

services: finviz-mcp: build: . ports: # Bind to localhost only on the host. Drop the "127.0.0.1:" prefix # only if you intentionally want public exposure — and read the # security note below first. - "127.0.0.1:8000:8000" environment: - MCP_TRANSPORT=sse - MCP_HOST=0.0.0.0 - MCP_PORT=8000 - FINVIZ_API_KEY=${FINVIZ_API_KEY} restart: unless-stopped

- MCP_TRANSPORT: Transport mode (stdio,sse, orstreamable-http)
- MCP_HOST: Host to bindinside the container(0.0.0.0is correct here so Docker can publish the port; restrict exposure on the host side via-p 127.0.0.1:8000:8000instead)
- MCP_PORT: Port to listen on (default:8000)

Security note: When you run the serverdirectly on the host(without Docker),MCP_HOSTdefaults to127.0.0.1(loopback). SetMCP_HOST=0.0.0.0only if you have a deliberate reason — public exposure requires DNS-rebinding protection at the application layer, which is tracked as Finding #6 inreviews/REVIEW_TRACKING.md.

# Find stocks with earnings today after market close earnings_screener( earnings_date="today_after", market_cap="large", min_price=10, min_volume=1000000, sectors=["Technology", "Healthcare"] )

# Find stocks with high volume and price increases volume_surge_screener( market_cap="smallover", min_price=10, min_relative_volume=1.5, min_price_change=2.0, sma_filter="above_sma200" )

# Get fundamental data for a single stock get_stock_fundamentals( ticker="AAPL", data_fields=["pe_ratio", "eps", "dividend_yield", "market_cap"] ) # Get fundamental data for multiple stocks get_multiple_stocks_fundamentals( tickers=["AAPL", "MSFT", "GOOGL"], data_fields=["pe_ratio", "eps", "market_cap"] )

earnings_premarket_screener( earnings_timing="today_before", market_cap="large", min_price=25, min_price_change=2.0, include_premarket_data=True )

earnings_afterhours_screener( earnings_timing="today_after", min_afterhours_change=5.0, market_cap="mid", include_afterhours_data=True )

trend_reversion_screener( market_cap="large", eps_growth_qoq=10.0, rsi_max=30, sectors=["Technology", "Healthcare"] )

uptrend_screener( trend_type="strong_uptrend", sma_period="20", relative_volume=2.0, price_change=5.0 )

dividend_growth_screener( min_dividend_yield=2.0, max_dividend_yield=6.0, min_dividend_growth=5.0, min_roe=15.0 )

Comprehensive stock information including:

- Basic info (ticker, company, sector, industry)
- Price and volume data
- Technical indicators (RSI, Beta, moving averages)
- Fundamental metrics (P/E, EPS, dividend yield)
- Earnings data (surprises, estimates, growth rates)
- Performance metrics (1w, 1m, YTD)

- Query parameters used
- List of matching stocks
- Total count and execution time
- Formatted output for easy reading

The server includes comprehensive error handling:

- Input validation for all parameters
- Rate limiting protection
- Network error recovery with retries
- Detailed error messages and logging

- Default 1-second delay between requests
- Configurable rate limiting
- Automatic retry with exponential backoff
- Finviz Elite API key support for higher limits

- DEBUG: Detailed request/response information
- INFO: General operation information (default)
- WARNING: Non-critical issues
- ERROR: Critical errors
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

This tool is for educational and research purposes only. Always conduct your own research before making investment decisions. The authors are not responsible for any financial losses incurred using this software.

For issues and feature requests, please use the GitHub issue tracker.

If you find this project helpful, consider supporting its development:

- Initial release
- Basic screening tools implementation
- Fundamental data retrieval
- MCP server integration
- Comprehensive error handling and validation

Search global news using natural language. Webz.io News Search API returns the most relevant articles and content, with filters for source, country, language, date, sentiment, and category.

An AI agent providing unified access to financial market data and news articles.

Shariah-compliant investing for AI agents — screen stocks & ETFs across 5 methodologies (AAOIFI, DJIM, FTSE, MSCI, S&P), audit portfolios, calculate zakat, get market data, news & SEC filings.

Real-time news with bias scoring across 5,000+ sources and 15+ dimensions, balanced news synthesis, live market data with AI analysis, ML options pricing, and semantic meme search.

Provides comprehensive enterprise risk analysis, including violation records, mortgage information, business anomalies, and judicial cases.

Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.

Deliver real-time investment research with extensive private and public market data.

Deep fundamental data from SEC filings, including operational KPIs not found on Bloomberg, built for your financial AI agents.

Access ROIC.AI financial data from AI tools, including company financials, ratios, prices, transcripts, and market research data.

Hosted MCP server for AI-enriched financial news — full-text and ticker-scoped news search, trending stories, and SEC Form 4 insider activity, each story scored 1–10 for relevance (OAuth 2.1, free tier 100 calls/hour).

Read-only MCP for U.S. household financial distress data: 96 indicators, the American Distress Index (ADI), and county-level distress scores for all 3,144 U.S. counties.