finviz-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Environment Setup

# Create virtual environment with Python 3.11+
python3.11 -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate     # On Windows

# Install dependencies in development mode
pip install -e .

Running the Server

# Start the MCP server (stdio mode)
finviz-mcp-server

# Alternative: Run directly with Python
python3 run_server.py

# Alternative: Run as module
python3 -m src.server

Testing

# Basic functionality test
python3 test_basic.py

# All features test
python3 test_all_features.py

# Live features test (requires API access)
python3 test_live_features.py

Code Quality

# Code formatting (if available)
black src/ --line-length 88

# Type checking (if mypy configured)
mypy src/

# Linting (if flake8 configured)
flake8 src/

Architecture Overview

Core Components

Server Architecture (src/server.py)

• FastMCP-based MCP server with 20+ financial screening tools
• Each tool is a decorated function that returns List[TextContent]
• Comprehensive error handling and logging for all tools
• Validates inputs using src/utils/validators.py

Client Architecture (src/finviz_client/)

• base.py: Core HTTP client with rate limiting and retry logic
• screener.py: Stock screening functionality with various filters
• news.py: News retrieval and processing
• sector_analysis.py: Sector and market performance analysis

Data Models (src/models.py)

• StockData: Comprehensive stock information with 70+ fields
• NewsData: News article information
• SectorPerformance: Sector performance metrics
• EarningsData: Earnings-specific data
• UpcomingEarningsData: Pre-earnings analysis data
• Field mappings for Finviz API integration

Utilities (src/utils/)

• validators.py: Input validation for all parameters
• formatters.py: Output formatting utilities