Financial Data MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a **Financial Data MCP Server** - a Model Context Protocol (MCP) server that provides comprehensive financial analysis tools. The server integrates with Claude Code to provide real-time stock data, portfolio analysis, technical analysis charts, and automated trading recommendations. ## Key Architecture ### Core Components 1. **financial_mcp_server.py** - Main MCP server implementation - Provides MCP tools and resources for financial data analysis - Uses **yfinance** (free Yahoo Finance scraper) - no API keys required - Implements MCP protocol handlers: `list_resources()`, `read_resource()`, `list_tools()`, `call_tool()` - Runs as an async server using `mcp.server.stdio` 2. **batch_fin_mcp_server.py** - Batch analysis engine - Analyzes all portfolios at once and generates comprehensive reports - Implements sophisticated trend analysis using 50-day and 200-day EMAs - Identifies 4 specific trading scenarios (A-D) based on price/EMA relationships - Skips stocks in downtrends, focuses only on uptrending stocks - Generates detailed charts for each stock with scenario analysis 3. **email_report_script.py** - Email automation - Sends batch analysis results via email with chart attachments - Saves buy recommendations to JSON for tracking - Requires email configuration in `email_config.json` 4. **daily_tracking_script.py** - Performance tracking - Monitors performance of buy recommendations over time - Creates tracking charts showing entry price vs current performance - Generates daily tracking reports with performance metrics ### Data Flow ``` portfolio.json → batch_fin_mcp_server.py → batch_financial_charts/ + report ↓ email_report_script.py → buy_recommendations.json ↓ daily_tracking_script.py → tracking_charts/ + report ``` ### Portfolio Structure The `portfolio.json` file uses this structure: ```json { "portfolio_name": { "portfolio": "Display Name", "stock_list": ["SYMBOL1", "SYMBOL2", ...] } } ``` ## Technical Analysis Logic The batch analyzer uses proven technical analysis principles: - **Trend Detection**: Combines 5 signals (Golden/Death Cross, price relative to EMAs, EMA slopes) - **Trading Scenarios**: - Scenario A: Price >10% above 50 EMA → SELL signal - Scenario B: Price above 50 EMA, touched recently → BUY signal - Scenario C: Price >5% below 50 EMA, decreasing 3+ days, above 200 EMA → BUY signal - Scenario D: Price below 50 EMA, touched 200 EMA recently → BUY signal ## Common Commands ### Running the MCP Server ```bash # Activate virtual environment first source mcp_fin_server_venv/bin/activate # Run the main MCP server (for Claude Code integration) python3 financial_mcp_server.py ``` ### Running Batch Analysis ```bash # Run batch analysis on all portfolios python3 batch_fin_mcp_server.py # Results saved to: batch_financial_charts/ ``` ### Email Reports ```bash # Configure email first (edit email_config.json) # Then send batch analysis report python3 email_report_script.py ``` ### Daily Tracking ```bash # Track performance of buy recommendations python3 daily_tracking_script.py # Results saved to: tracking_charts/ ``` ### Installing Dependencies ```bash # Install from requirements.txt pip install -r requirements.txt # Or use clean requirements (recommended) pip install -r clean_requirements.txt ``` ## MCP Integration When integrating with Claude Code, the server needs to be configured in Claude's MCP settings. The server provides: **Tools:** - `load_portfolio` - Load portfolio data from portfolio.json - `analyze_portfolio` - Deep analysis of specific portfolio - `portfolio_performance` - Performance metrics over time periods - `get_stock_info` - Comprehensive stock information - `get_earnings_calendar` - Upcoming earnings announcements - `get_analyst_changes` - Recent analyst upgrades/downgrades - `generate_macd_chart` - MACD technical analysis charts - `get_market_overview` - Major market indices status **Resources:** - `financial://portfolio/overview` - Portfolio summary - `financial://earnings/today` - Today's earnings reports - `financial://market/status` - Current market status ## Important Notes - **No API Keys Required**: Uses free yfinance library (Yahoo Finance scraper) - **Charts Directory**: Charts are saved to project-relative paths, not home directory - **Virtual Environment**: Use `mcp_fin_server_venv/` for all Python operations - **Headless Charts**: matplotlib configured with 'Agg' backend for batch operations - **JSON Serialization**: Special handling for numpy/pandas types to avoid serialization errors - **Logging**: Main server logs to `/tmp/financial_mcp_server.log` and stderr ## File Locations - Portfolio data: `portfolio.json` (project root) - Batch charts: `batch_financial_charts/` - Tracking charts: `tracking_charts/` - Email config: `email_config.json` (create from template) - Buy recommendations: `buy_recommendations.json` (auto-generated) - Tracking history: `tracking_history.json` (auto-generated) - Virtual environment: `mcp_fin_server_venv/` - MCP HTTP Bridge: `mcp-http-bridge/` (Node.js Express server for HTTP access)