Finviz MCP Server

English | 日本語

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

Features

Stock Screening Tools

• 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

Fundamental Analysis

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

Technical Analysis

• 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
• Relative volume analysis
• 52-week high/low tracking

📄 SEC Filing Features

17. 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)
    

Installation

Prerequisites

• 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

Setup

1. Clone and setup the project:

# 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 .

2. Configure environment variables:

# 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

3. Test the installation:

# Test if the server starts correctly (press Ctrl+C to stop)
finviz-mcp-server

# You should see the server starting in stdio mode

Configuration

The server can be configured using environment variables:

• FINVIZ_API_KEY: Your Finviz Elite API key (required for Elite features, improves rate limits)
• MCP_SERVER_PORT: Server port (default: 8080)
• LOG_LEVEL: Logging level (default: INFO)
• RATE_LIMIT_REQUESTS_PER_MINUTE: Rate limiting (default: 100)
• EDGAR_USER_AGENT: Required only for the EDGAR API tools (get_edgar_filing_content, get_multiple_edgar_filing_contents, get_edgar_company_filings, get_edgar_company_facts, get_edgar_company_concept). SEC requires a non-empty User-Agent header on every request — set this to something like "Your Name your.email@example.com". The Finviz SEC listing tools (get_sec_filings, get_major_sec_filings, get_insider_sec_filings, get_sec_filing_summary) do not require this variable.

Note: While the API key is technically optional, many advanced screening features require a Finviz Elite subscription and API key to function properly.

Usage

Running the MCP Server

The server runs as a stdio-based MCP server:

# Make sure virtual environment is activated
source venv/bin/activate

# Run the server
finviz-mcp-server

Integration with Claude Desktop

Add the server to your Claude Desktop MCP c

... View full README on GitHub