MCP Securities Analysis

# Equity Research and Portfolio Management Skills A collection of Claude Code skills for automated equity research and portfolio analysis. ## Overview **Stock Research Skills** - Automated equity research report generation using multi-phase data gathering and AI-powered analysis All skills can be run independently or orchestrated together for complex workflows.Quick Start ### Quick Start ```bash # Clone the git repo including this file into a project directory like mcpskills git clone https://github.com/druce/MCP.git cd MCP/mcpskills # Create conda environment, OpenBB needs < 3.14 conda create --name mcpskills python=3.11 # Activate conda environment conda activate mcpskills # Install Python dependencies pip install -r requirements.txt # TA-Lib requires system library (macOS) # for other platforms check https://ta-lib.org/install/ brew install ta-lib export TA_INCLUDE_PATH="$(brew --prefix ta-lib)/include" export TA_LIBRARY_PATH="$(brew --prefix ta-lib)/lib" # Install pandoc for document conversion # optional for last step, otherwise will only create .md, no docx/html) # https://pandoc.org/installing.html brew install pandoc # Update API keys cp dot-env.txt .env # edit file with Claude, Perplexity, OpenBB keys, and SEC email self-reporting # Complete research for a stock (all phases) ./skills/research_stock.py TSLA # Run specific phases only ./skills/research_stock.py TSLA --phases technical,fundamental,report # With custom peer companies ./skills/research_stock.py TSLA --peers "GM,F,TM,RIVN" ``` ## Project Structure ``` mcpskills/ ├── work/ # Stock research outputs │ └── {SYMBOL}_{YYYYMMDD}/ # Per-stock research directories │ ├── 00_metadata.json │ ├── 01_technical/ │ ├── 02_fundamental/ │ ├── 03_research/ │ ├── 04_sec/ │ ├── 05_wikipedia/ │ ├── 06_analysis/ │ ├── 08_deep_research/ │ ├── research_report.md │ ├── final_report.md │ ├── final_report.docx │ └── final_report.html ├── import/ # Fidelity CSV exports for portfolio analysis (Portfolio_Positions_*.csv) ├── data/ # Aggregated portfolio data and mappings │ ├── aggregate_positions.csv │ ├── aggregate_positions_YYYYMMDD.csv │ └── security_mapping.csv ├── dataviz/ # Interactive portfolio visualizations │ └── allocation_sunburst_YYYYMMDD.html ├── skills/ # All executable skills │ ├── research_stock.py # Research orchestrator │ ├── lookup_ticker.py │ ├── research_technical.py │ ├── research_fundamental.py │ ├── research_perplexity.py │ ├── research_sec.py │ ├── research_wikipedia.py │ ├── research_analysis.py │ ├── research_report.py │ ├── research_deep.py │ ├── research_final.py │ ├── filter_peers.py │ ├── aggregate_positions.py │ ├── visualize_allocation.py │ └── README.md # Detailed skill documentation ├── templates/ # Jinja2 report templates │ ├── equity_research_report.md.j2 │ ├── analyst_report.md.j2 │ └── final_report.md.j2 ├── CLAUDE.md # Instructions for Claude Code ├── EQUITY_RESEARCH_PROCESS.md # Research workflow documentation └── README.md # This file ``` ## Stock Research Skills ### Research Workflow The stock research system uses a **multi-phase pipeline** orchestrated by `research_stock.py` that executes in three stages: **Stage 1: Technical Analysis (Sequential)** - Technical phase runs first to generate peer list needed by other phases **Stage 2: Data Gathering (Parallel)** - Fundamental, research, analysis, SEC, and Wikipedia phases run concurrently using the peer list **Stage 3: Report Generation (Sequential)** - Report synthesis, deep research, and final assembly phases run in order **IMPORTANT:** If running phases manually, always run technical before fundamental, as fundamental depends on the peer list generated by technical. ### Core Orchestrator **research_stock.py** - Main orchestrator coordinating the entire research workflow ```bash # Complete research with all phases ./skills/research_stock.py TSLA # Run specific phases ./skills/research_stock.py INTC --phases technical,fundamental,research,report # With custom peer companies ./skills/research_stock.py TSLA --peers "GM,F,TM,RIVN" # Keep old directories (don't cleanup) ./skills/research_stock.py AAPL --skip-cleanup ``` **Process:** 1. Validates ticker symbol 2. Creates `work/{SYMBOL}_{YYYYMMDD}` directory 3. Executes data gathering phases in parallel (max 6 workers) 4. Executes report generation phases sequentially 5. Outputs comprehensive research report in multiple formats ### Research Phase Skills Each phase is a standalone skill that can be run independently: #### 1. lookup_ticker.py Ticker symbol lookup and validation using OpenBB API. ```bash ./skills/lookup_ticker.py "Tesla" ./skills/lookup_ticker.py "Broadcom" --limit 5 --save ``` #### 2. research_technical.py Technical analysis phase - generates charts and calculates technical indicators. **Output:** `01_technical/` - `chart.png` - 4-year weekly candlestick chart with MA13, MA52, volume, relative strength - `technical_analysis.json` - Technical indicators (SMA, RSI, MACD, ATR, Bollinger Bands) - `peers_list.json` - Identified peer companies #### 3. research_fundamental.py Fundamental analysis phase - gathers financial data and company fundamentals. **Output:** `02_fundamental/` - `company_overview.json` - Company profile, market data, valuation metrics - `income_statement.csv` - Historical income statements - `balance_sheet.csv` - Historical balance sheets - `cash_flow.csv` - Historical cash flow statements - `key_ratios.csv` - 5-year financial ratios (from OpenBB/FMP) - `analyst_recommendations.json` - Analyst ratings and price targets - `news.json` - Recent news articles #### 4. research_perplexity.py Perplexity AI research phase - deep research using AI for qualitative analysis. **Output:** `03_research/` - `news_stories.md` - Major news since 2024 (10-15 stories with sources) - `business_profile.md` - 10-section comprehensive business analysis - `executive_profiles.md` - C-suite profiles and backgrounds #### 5. research_sec.py SEC filings research phase - downloads and parses official 10-K filings. **Output:** `04_sec/` - `10k_item1.txt` - Item 1 (Business Description) from latest 10-K - `10k_metadata.json` - Filing metadata #### 6. research_wikipedia.py Wikipedia research phase - fetches company information. **Output:** `05_wikipedia/` - `wikipedia_summary.txt` - Wikipedia page summary - `wikipedia_metadata.json` - Page metadata #### 7. research_analysis.py Deep analysis phase - generates analytical insights using Perplexity AI. **Output:** `06_analysis/` - `business_model_analysis.md` - 5-section deep dive on business model - `competitive_analysis.md` - Competitive landscape and dynamics - `risk_analysis.md` - Recent news, analyst reports, legal/regulatory issues - `investment_thesis.md` - SWOT, bull/bear cases, critical watch points #### 8. research_report.py Report generation phase - assembles comprehensive analyst-style research report. **Output:** - `research_report.md` - Comprehensive markdown research report synthesizing all phase data #### 9. research_deep.py Deep research phase - comprehensive analysis using Claude Agent SDK with MCP tools. **Output:** `08_deep_research/` - `deep_research_output.md` - 9-section comprehensive analysis (~10K-20K characters) - `deep_research_thinking.md` - Extended thinking process from Claude - `tool_usage.txt` - Log of MCP tools used during research **Features:** - Uses Claude Sonnet 4.5 with extended thinking (10K token budget) - Access to 6 MCP servers for real-time data gathering (stock-symbol-server, alphavantage, yfinance, brave-search, perplexity-ask, wikipedia) - Hybrid mode: receives research_report.md as context, uses MCP tools to fill gaps - Execution time: 2-5 minutes with tools, cost ~$1-2 per run **Report Sections:** 1. Short Summary Overall Assessment 2. Extended Profile (history, core business, recent news) 3. Business Model (revenue streams, customer segments, competitive advantages) 4. Competitive Landscape (competitors, market share, differentiation) 5. Supply Chain Positioning 6. Financial & Operating Leverage 7. Valuation (methodologies, multiples, analyst opinions) 8. Recent Developments & Risk Factors 9. Conclusion (SWOT, bull/bear cases, watch points) #### 10. research_final.py Final report assembly phase - combines all research into polished final report with multi-format export. **Output:** - `final_report.md` - Final polished markdown report - `final_report.docx` - Word document (if pandoc or python-docx available) - `final_report.html` - Standalone HTML report (if pandoc or markdown available) **Report Structure:** 1. Executive Summary 2. Stock Chart (4-year weekly with technical indicators) 3. Technical Analysis Summary (key indicators table, trend signals) 4. Peer Comparison (enhanced 8-column table with financial metrics) 5. Comprehensive Deep Research Analysis (full 9-section analysis) 6. Investment Conclusion (strategic position, SWOT, watch points) #### 11. filter_peers.py Peer filtering utility - filters and ranks peer companies based on relevance criteria. ## Development ### Python Environment This project requires **Python 3.11** (for OpenBB compatibility). Use conda for environment management: ```bash # Clone the git repo including this file git clone https://github.com/druce/MCP.git cd MCP/mcpskills # Create conda environment, OpenBB needs < 3.14 conda create --name mcpskills python=3.11 # Activate conda environment conda activate mcpskills # Install Python dependencies pip install -r requirements.txt # TA-Lib requires system library (macOS) # for other platforms check https://ta-lib.org/install/ brew install ta-lib export TA_INCLUDE_PATH="$(brew --prefix ta-lib)/include" export TA_LIBRARY_PATH="$(brew --prefix ta-lib)/lib" # Install pandoc for document conversion # optional for last step, otherwise will only create .md, no docx/html) # https://pandoc.org/installing.html brew install pandoc ``` ### Required API Keys #### Setup Instructions 1. **Copy the template file** to create your `.env` file: ```bash cp dot-env.txt .env ``` 2. **Add your API keys** to the `.env` file. Open it in a text editor and replace the empty strings with your actual keys: ```bash # SEC EDGAR credentials (required for SEC filings) # Your company name and email for SEC API User-Agent SEC_USER='your_email@example.com' SEC_FIRM='YourCompanyName' # Perplexity AI API key (required for research and analysis phases) # Get yours at: https://www.perplexity.ai/settings/api PERPLEXITY_API_KEY='your_perplexity_key_here' # Finnhub API key (RECOMMENDED - free tier for peer lookup and symbol validation) # Get yours at: https://finnhub.io/register FINNHUB_API_KEY='your_finnhub_key_here' # Anthropic Claude API key (optional - for deep research phase) # Get yours at: https://console.anthropic.com/ ANTHROPIC_API_KEY='your_anthropic_api_key_here' # OpenBB Platform Personal Access Token (optional fallback for peer lookup) # Get yours at: https://my.openbb.co/app/platform/pat # Note: FMP peers endpoint may require paid subscription OPENBB_PAT='your_openbb_pat_here' ``` **Data Source Priority:** - Symbol validation/lookup: yfinance → Finnhub → OpenBB+FMP - Peer lookup: Finnhub → OpenBB+FMP - Fundamental data: yfinance (primary) #### Where to Get API Keys **Required:** - **SEC EDGAR**: No API key needed, just provide your company name and email address for the User-Agent header (required by SEC) - **Perplexity AI API**: Create an account and generate an API key at [https://www.perplexity.ai/settings/api](https://www.perplexity.ai/settings/api) - [Perplexity API Documentation](https://docs.perplexity.ai/) - Note: API access is billed separately from Pro subscription **Recommended:** - **Finnhub API** (RECOMMENDED): Create a free account and generate an API key at [https://finnhub.io/register](https://finnhub.io/register) - [Finnhub API Documentation](https://finnhub.io/docs/api) - Free tier provides 60 API calls per minute - Used for peer company detection and symbol validation - Primary data source with automatic fallback to OpenBB if unavailable **Optional:** - **Anthropic Claude API**: Sign up and create an API key at [https://console.anthropic.com/](https://console.anthropic.com/) - [Claude API Documentation](https://docs.anthropic.com/claude/reference/getting-started-with-the-api) - Note: Includes free credits to get started, then pay-as-you-go pricing - Optional for deep research phase - **OpenBB Platform PAT**: Create a free account and generate a Personal Access Token at [https://my.openbb.co/app/platform/pat](https://my.openbb.co/app/platform/pat) - [OpenBB Platform Documentation](https://docs.openbb.co/platform) - Optional fallback for peer lookup (note: FMP peers may require paid subscription) - Only needed if Finnhub is not configured ### Dependencies **Core (Both Systems):** - Python 3.11+ - pandas >= 2.0 - python-dotenv **Stock Research - Data Gathering:** - yfinance (stock data and fundamentals - primary data source) - finnhub-python (peer company detection and symbol validation - recommended) - openbb (OpenBB Platform - optional fallback for peers) - numpy - plotly >= 5.0 (for chart generation) - talib (TA-Lib for technical indicators) - openai (for Perplexity API - OpenAI-compatible) - sec-edgar-downloader (for SEC filings) - beautifulsoup4 (for HTML parsing) - wikipediaapi (for Wikipedia data) **Stock Research - Report Generation:** - jinja2 (for report templating) - anthropic (for Claude API access) - claude-agent-sdk (for MCP server integration in deep research) - mcp (Model Context Protocol) - python-docx (optional, for Word document generation) - lxml (for XML/HTML parsing) - markdown (optional, for HTML report generation) **Portfolio Management:** - plotly >= 5.0 (for visualizations) ### MCP Server Configuration (Optional) The deep research phase (`research_deep.py`) can optionally use MCP servers for real-time data access. This is **not required** for basic research workflows. If you want to enable MCP servers for enhanced deep research capabilities, configure them in `~/Library/Application Support/Claude/claude_desktop_config.json`: **Supported MCP servers:** - `stock-symbol-server` - Local server.py with financial tools - `alphavantage` - Alpha Vantage financial data - `yfinance` - Yahoo Finance data - `brave-search` - Web search - `perplexity-ask` - AI-powered search - `wikipedia` - Company information **Note:** The deep research phase works without MCP servers by using the initial research report as context. MCP servers enhance results by providing real-time data access during the deep research analysis. See CLAUDE.md for details on MCP server setup. ### Creating New Skills Skills should follow these conventions: 1. **Shebang:** `#!/opt/anaconda3/envs/mcpskills/bin/python3` 2. **Executable:** `chmod +x skills/your_skill.py` 3. **Docstring:** Include usage instructions at top of file 4. **Arguments:** Use argparse for directory paths and options 5. **Error Handling:** Graceful failures with helpful messages 6. **Output:** Create directories as needed, use dated archives 7. **Documentation:** Update `skills/README.md` with skill details 8. **Return codes:** Return 0 for success, 1 for failure ## Workflows ### Stock Research Workflow Complete equity research for a stock: 1. **Run the orchestrator** to execute all phases ```bash ./skills/research_stock.py TSLA ``` 2. **Review outputs** in `work/TSLA_YYYYMMDD/` - Check phase directories for gathered data - Review `research_report.md` for initial synthesis - Review `final_report.md` for polished analysis 3. **View reports** in multiple formats - Open `final_report.html` in browser for interactive viewing - Open `final_report.docx` in Word for editing/sharing - Read `final_report.md` for markdown format 4. **Optional: Run specific phases independently** ```bash # Update just the report with a different template ./skills/research_report.py TSLA --work-dir work/TSLA_20251220 --template analyst_report.md.j2 # Re-run deep research ./skills/research_deep.py TSLA --work-dir work/TSLA_20251220 # Regenerate final report ./skills/research_final.py TSLA --work-dir work/TSLA_20251220 ``` ## File Locations **Stock Research:** - **Skills:** `skills/research_*.py` - Research phase scripts - **Templates:** `templates/*.md.j2` - Jinja2 report templates - **Work Output:** `work/{SYMBOL}_{YYYYMMDD}/` - Per-stock research directories **Documentation:** - **skills/README.md** - Comprehensive skill documentation (1000+ lines) - **CLAUDE.md** - Instructions for Claude Code - **EQUITY_RESEARCH_PROCESS.md** - Detailed research workflow - **spec.md** - Portfolio skills development plan ## Important Notes **Stock Research:** - All skills are executable: `chmod +x skills/*.py` - Working directory auto-set to script location on startup - Older work directories deleted by default (use `--skip-cleanup` to preserve) - Report generation works with partial data if phases fail - Deep research phase requires claude-agent-sdk and configured MCP servers - Multi-format export requires pandoc (preferred) or python libraries (fallback) ## Related Files See also: - **skills/README.md** - Detailed documentation of all skills (1000+ lines) - **CLAUDE.md** - Development guide for Claude Code - **EQUITY_RESEARCH_PROCESS.md** - Research workflow and best practices ## License This is a personal research and portfolio management tool. No license specified. ## Support For detailed documentation of each skill's functionality and usage, see **skills/README.md** which provides comprehensive documentation including: - Detailed usage instructions for each skill - Input/output specifications - Data sources and API requirements - Feature descriptions and capabilities - Example outputs and workflows