Stockresearchmcp — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited Stockresearchmcp (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
A sophisticated multi-agent Model Context Protocol (MCP) server for comprehensive stock research and analysis. Query any sector or industry using natural language and get instant, detailed analysis backed by SEC filings and real-time market data.
Three Specialized Agents Working Together:
When you query any sector/industry:
# 1. Navigate to project directory
cd /Users/pradeepsahu/dev_data/StockSearhMCP
# 2. Create virtual environment
python3 -m venv .venv
# 3. Activate virtual environment
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
# 4. Install dependencies
pip install -e .
# 5. Set environment variables
export OPENAI_API_KEY="your-openai-api-key"
export SEC_API_USER_AGENT="YourCompany [email protected]"
# 6. (Optional) Test installation
python test_installation.py# Quick test - should show analysis of technology stocks
python examples/basic_usage.py✨ NEW: ChromaDB builds automatically on your first query - no manual setup required!
Set these in your MCP configuration (see Configuration section below):
# Required: OpenAI API key for embeddings
OPENAI_API_KEY="your-openai-api-key"
# Required: SEC-compliant User-Agent
SEC_API_USER_AGENT="Your Company Name [email protected]"
# Optional: Customize ChromaDB storage location (default: ./chroma_db)
CHROMA_PERSIST_DIR="./chroma_db"
# Optional: Adjust processing (lower = faster but fewer companies)
MAX_WORKERS="4" # Parallel downloads (default: 4)
BATCH_SIZE="32" # Embedding batch size (default: 32)If you prefer to build ChromaDB before your first query:
cd /Users/pradeepsahu/dev_data/StockSearhMCP
source .venv/bin/activate
# Set environment variables
export OPENAI_API_KEY="your-key"
export SEC_API_USER_AGENT="YourCompany [email protected]"
# Run builder
python src/sector/builder.pyNote: First-time build takes 20-40 minutes. You'll see progress updates during the build.
Add to your MCP settings file to connect with Claude Desktop or other MCP clients.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"stock-research": {
"command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/python",
"args": [
"-m",
"stock_research_mcp.server"
],
"env": {
"PYTHONPATH": "/Users/pradeepsahu/dev_data/StockSearhMCP/src",
"OPENAI_API_KEY": "your-openai-api-key-here",
"SEC_API_USER_AGENT": "YourCompany [email protected]",
"CHROMA_PERSIST_DIR": "/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db",
"USE_REAL_API": "true",
"USE_CHROMA_SECTORS": "true",
"MAX_WORKERS": "4",
"BATCH_SIZE": "32"
}
}
}
}After installation, you can also use:
{
"mcpServers": {
"stock-research": {
"command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/stock-research-mcp",
"env": {
"OPENAI_API_KEY": "your-openai-api-key-here",
"CHROMA_PERSIST_DIR": "/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db",
"USE_REAL_API": "true",
"USE_CHROMA_SECTORS": "true"
}
}
}
}Edit %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"stock-research": {
"command": "python",
"args": [
"-m",
"stock_research_mcp.server"
],
"env": {
"PYTHONPATH": "C:\\Users\\YourUsername\\dev_data\\StockSearhMCP\\src",
"OPENAI_API_KEY": "your-openai-api-key-here",
"SEC_API_USER_AGENT": "YourCompany [email protected]",
"CHROMA_PERSIST_DIR": "C:\\Users\\YourUsername\\dev_data\\StockSearhMCP\\output\\chroma_db",
"USE_REAL_API": "true",
"USE_CHROMA_SECTORS": "true",
"MAX_WORKERS": "4",
"BATCH_SIZE": "32"
}
}
}
}Launch the web interface for a user-friendly experience:
# Option 1: Using launch script
./launch_gradio.sh
# Option 2: Direct Python
python gradio_app.pyAccess at: http://localhost:7860
Features:
Example Usage:
Advantages:
Use through Claude Desktop for AI-powered interaction:
Once configured (see Configuration section), Claude automatically decides when to use the tool.
✅ Queries that trigger the tool:
"Analyze technology stocks"
"Show me healthcare sector analysis"
"What are the best semiconductor companies?"
"Use analyze_sector for renewable energy"
"Search for biotechnology stocks"❌ Queries that might NOT trigger the tool:
"Tell me about stocks" (too vague - Claude uses general knowledge)
"What's a good investment?" (general advice, not sector-specific)
"Explain the stock market" (educational, not analysis)💡 Pro Tips:
🎬 First Query Flow (one-time setup):
User asks: "Analyze biotechnology sector"
↓
System detects: No ChromaDB found
↓
Automatic Build Starts (streaming progress):
📥 Step 1: Fetching company tickers from SEC → 8,000 companies
📄 Step 2: Downloading filings (20-40 min)
Progress: 100/8000, 200/8000... (updates every 10 companies)
💾 Indexing batches to ChromaDB
🔍 Step 3: Verifying index
✅ Step 4: Build complete! → 7,500 companies indexed
↓
Query Execution:
- Semantic search finds biotechnology companies
- Multi-agent analysis runs
- Results displayed⚡ Subsequent Queries (instant - <1 second):
User asks: "Show me semiconductor stocks"
↓
ChromaDB Semantic Search (instant):
- Convert "semiconductor" to embedding
- Find matches in SEC filings
- Returns: NVDA, AMD, INTC, QCOM, etc.
↓
Multi-Agent Processing:
├─→ Search Agent: Fetch real-time prices (Yahoo Finance)
├─→ Categorization Agent: Group by price ranges
└─→ Analysis Agent: News, events, recommendations
↓
Comprehensive Report (formatted & delivered)Technology:
Healthcare:
Other Industries:
Natural Language Works! The ChromaDB semantic search understands your intent based on SEC filing business descriptions, so you can query any industry using natural language.
#### analyze_sector
Description: Performs comprehensive multi-agent analysis on any sector or industry.
Parameters:
sector (string, required): Natural language description of sector/industrySupported Sectors:
Examples:
{"sector": "technology"}
{"sector": "biotechnology"}
{"sector": "renewable energy"}
{"sector": "artificial intelligence"}
{"sector": "semiconductor manufacturing"}View MCP Server Logs:
# Follow live logs
tail -f ~/Library/Logs/Claude/mcp-server-stock-research.log
# View last 100 lines
tail -100 ~/Library/Logs/Claude/mcp-server-stock-research.log
# Search for errors
grep "ERROR" ~/Library/Logs/Claude/mcp-server-stock-research.log
# View analysis reports
grep -A 50 "STOCK ANALYSIS REPORT" ~/Library/Logs/Claude/mcp-server-stock-research.log
# Search for specific stock
grep "AAPL" ~/Library/Logs/Claude/mcp-server-stock-research.logWhat You'll See in Logs:
Processing sector analysis request for: technologyFetched AAPL: $276.97[StockSearchAgent], [StockCategorizationAgent], [StockAnalysisAgent]Found 15 stocks in technology sector┌─────────────────────────────────────────────────────────────┐
│ USER QUERY │
│ "Analyze stocks in biotechnology sector" │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP SERVER (server.py) │
│ - Receives query via stdio │
│ - Validates input │
│ - Routes to orchestrator │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (orchestrator.py) │
│ - Coordinates all 3 agents │
│ - Manages workflow pipeline │
│ - Formats final output │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────┴────────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────────┐
│ STEP 1: SEARCH │ │ ChromaDB Integration │
│ ─────────────── │ │ ─────────────────── │
│ StockSearchAgent │ │ • Semantic search │
│ │◄────────┤ • 8,000+ companies │
│ Actions: │ │ • SEC filings data │
│ • Query ChromaDB │ │ • Natural language │
│ • Yahoo Finance │ └─────────────────────────┘
│ • Return stocks │
└──────────┬──────────┘
│
▼
┌─────────────────────────┐
│ STEP 2: CATEGORIZE │
│ ─────────────────── │
│ StockCategorization │
│ │
│ • High: >$100 │
│ • Medium: $10-$100 │
│ • Low: <$10 │
└──────────┬──────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ STEP 3: ANALYZE (for each stock) │
│ ───────────────────────────── │
│ StockAnalysisAgent │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Price Analysis: trend, momentum, support │ │
│ └──────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────┐ │
│ │ News Collection: sentiment, sources │ │
│ └──────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Events: earnings, dividends, launches │ │
│ └──────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Recommendations: signals, advice, risk │ │
│ └──────────────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FORMATTED REPORT │
│ ═══════════════════════════════════════════════════ │
│ STOCK ANALYSIS REPORT - BIOTECHNOLOGY SECTOR │
│ ═══════════════════════════════════════════════════ │
│ HIGH-VALUE STOCKS (7): MRNA, GILD, BIIB... │
│ MEDIUM-VALUE STOCKS (12): VRTX, REGN... │
│ LOW-VALUE STOCKS (8): Small caps... │
│ │
│ Full analysis with news, events, recommendations │
└─────────────────────────────────────────────────────────────┘Key Innovation: Semantic search on SEC filing data enables natural language understanding of sectors/industries - no hardcoded mappings required!
StockSearhMCP/
├── src/
│ ├── stock_research_mcp/ # Main package
│ │ ├── server.py → MCP server entry point
│ │ ├── types.py → Pydantic data models
│ │ └── agents/ → Multi-agent system
│ │ ├── orchestrator.py → Coordinates all agents
│ │ ├── stock_search_agent.py → Agent 1: Search
│ │ ├── stock_categorization_agent.py → Agent 2: Categorize
│ │ ├── stock_analysis_agent.py → Agent 3: Analyze
│ │ ├── sector_ticker_fetcher.py → ChromaDB helper
│ │ └── real_api_fetcher.py → Yahoo Finance integration
│ └── sector/ # ChromaDB build system
│ ├── builder.py → Main build script
│ ├── fetch_tickers.py → Get companies from SEC
│ ├── fetch_filings.py → Download 10-K/10-Q filings
│ ├── extract_text.py → Extract business descriptions
│ ├── embeddings_and_chroma.py → OpenAI + ChromaDB
│ └── search_api.py → Optional: FastAPI interface
├── gradio_app.py # Web interface
├── test_gradio_setup.py # Gradio verification
├── launch_gradio.sh # Launch script
├── examples/
│ ├── basic_usage.py # Simple example
│ └── real_api_integration.py # API integration demo
└── output/
└── chroma_db/ # ChromaDB persistent storageStock # Company information
├── symbol: str # AAPL, MSFT, etc.
├── name: str # Apple Inc.
├── price: float # 175.43
├── sector: str # Technology
├── market_cap: float # Optional
├── change: float # +1.35
└── change_percent: float # +0.77%
StockCategory (Enum) # Price ranges
├── HIGH (> $100)
├── MEDIUM ($10-$100)
└── LOW (< $10)
PriceAnalysis # Technical analysis
├── current_price: float
├── trend: str # bullish/bearish
├── support: float # Support level
└── resistance: float # Resistance level
NewsItem # News articles
├── title: str
├── source: str
├── date: str
├── sentiment: str # positive/negative/neutral
└── summary: str
EventItem # Upcoming events
├── type: str # Earnings Call, Dividend, etc.
├── date: str
├── description: str
└── impact: str # high/medium/low
StockAnalysis # Complete analysis
├── stock: Stock
├── category: StockCategory
├── price_analysis: PriceAnalysis
├── news: List[NewsItem]
├── events: List[EventItem]
└── recommendation: str# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest# Format code with Black
black src/
# Type checking with mypy
mypy src/# Run the server directly
python -m stock_research_mcp.server
# Or use the installed script
stock-research-mcpThe system is fully integrated with real APIs and provides live market data:
1. Yahoo Finance (yfinance) - Exclusive live data source
2. ChromaDB with SEC EDGAR
For extended functionality, you can add:
# In stock_search_agent.py
import os
import requests
async def _fetch_stocks_from_source(self, sector: str) -> List[Stock]:
api_key = os.getenv("ALPHA_VANTAGE_API_KEY")
url = f"https://www.alphavantage.co/query?function=SECTOR&apikey={api_key}"
response = requests.get(url)
data = response.json()
# Parse and return Stock objects
return stocksRecommended APIs:
Additional News Sources:
Note: The system already fetches real news from Yahoo Finance via yfinance library.
Additional Event Sources:
Note: The system already fetches real earnings dates, dividend schedules, and ex-dividend dates from Yahoo Finance.
Create a .env file:
# .env
ALPHA_VANTAGE_API_KEY=your_key_here
NEWS_API_KEY=your_key_here
FINNHUB_API_KEY=your_key_here
POLYGON_API_KEY=your_key_hereLoad in your code:
from dotenv import load_dotenv
load_dotenv()Install python-dotenv:
pip install python-dotenvThe system generates comprehensive reports with this format:
================================================================================
STOCK ANALYSIS REPORT - TECHNOLOGY SECTOR
================================================================================
Total Stocks Analyzed: 10
────────────────────────────────────────────────────────────────────────────────
HIGH-VALUE STOCKS (Price > $100)
────────────────────────────────────────────────────────────────────────────────
📊 AAPL - Apple Inc.
Price: $175.43 | Change: 1.35%
Trend: bullish
📰 Recent News (3):
• Apple reports quarterly earnings [positive]
• Analysts upgrade AAPL rating [positive]
📅 Upcoming Events (3):
• Earnings Call - 2025-12-19 [high impact]
• Dividend Payment - 2025-12-04 [medium impact]
💡 Recommendation:
Stock shows positive momentum. News sentiment is generally positive...Problem: ChromaDB not found / No stocks returned
✅ Solutions:
# 1. Verify ChromaDB exists
ls -la output/chroma_db/
# 2. Check environment variable
echo $CHROMA_PERSIST_DIR
# 3. Rebuild if needed
python src/sector/builder.py
# 4. Use absolute path in MCP config
CHROMA_PERSIST_DIR="/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db"Problem: ChromaDB query error: "Expected include item to be..."
✅ Status: FIXED in latest version
query() always returns ids by default"ids" from include parametersrc/stock_research_mcp/agents/sector_ticker_fetcher.py if neededProblem: Claude Desktop doesn't show the tool
✅ Complete Checklist:
# Must be in user home, not system /Library
~/Library/Application Support/Claude/claude_desktop_config.json "command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/python"❌ NOT: "python" or "python3"
"OPENAI_API_KEY": "sk-proj-actual-key-here"❌ NOT: "your-openai-api-key-here"
# Quit (Cmd+Q), wait 5 sec, reopen tail -f ~/Library/Logs/Claude/mcp*.logTest Server Manually:
cd /Users/pradeepsahu/dev_data/StockSearhMCP
source .venv/bin/activate
python -m stock_research_mcp.server
# Should show: "Stock Research MCP Server starting..."
# Press Ctrl+D to exitForce Tool Usage in Claude:
Problem: Server won't start
# Check Python version (need 3.10+)
python --version
# Activate virtual environment
source .venv/bin/activate
# Reinstall dependencies
pip install -e .
# Verify OpenAI key
echo $OPENAI_API_KEYProblem: Import errors
# Check PYTHONPATH in MCP config
echo $PYTHONPATH
# Verify all files exist
ls -la src/stock_research_mcp/agents/
# Check ChromaDB access
ls -la output/chroma_db/Problem: SEC 403 Forbidden Error
✅ Set SEC-compliant User-Agent:
export SEC_API_USER_AGENT="YourCompany [email protected]"Problem: OpenAI API Error
✅ Solutions:
# Verify key is valid
echo $OPENAI_API_KEY
# Check quota/billing
# Visit: https://platform.openai.com/usageProblem: Download timeouts
✅ Reduce workers:
export MAX_WORKERS="4" # Instead of 8
export BATCH_SIZE="32" # Instead of 64Problem: Port 7860 already in use
# Kill existing process
lsof -ti:7860 | xargs kill -9
# Or change port in gradio_app.py
server_port=8080 # Use different portProblem: Missing Gradio
pip install gradio
# Or
uv pip install gradioProblem: OpenAI key not working
Check .env file:
cat .env
# Should have: OPENAI_API_KEY=sk-proj-actual-keyRebuild the ChromaDB index when:
# Option 1: Full rebuild (deletes old data)
rm -rf output/chroma_db/
python src/sector/builder.py
# Option 2: Incremental update (builder will add/update)
python src/sector/builder.pyInclude more/fewer companies: Edit src/sector/fetch_tickers.py to filter by market cap, exchange, etc.
Add specific tickers: Create a custom ticker list JSON file and modify builder.py
Change filing types: Edit candidates list in src/sector/fetch_filings.py:
candidates = ["10-K", "20-F", "S-1", "10-Q"] # Modify as neededContributions are welcome! Areas for improvement:
MIT License
IMPORTANT: This tool is for educational and research purposes only. While the system uses real market data from Yahoo Finance, investment recommendations are algorithmically generated and should NOT be used as the sole basis for actual investment decisions.
logs/ directory for debuggingBuilt with ❤️ using Python and the Model Context Protocol
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.