Local Stock Analyst MCP (Python)

MCP server for stock intelligence workflows with:

• Domain-split tool registry (market, stocks, technical, fundamental, options, risk, news, screener)
• Multi-provider adapters with fallback routing
• In-memory TTL caching and per-provider rate-limit guards
• stdio and Render-compatible HTTP transport modes

Provider Support

• Finnhub
• Alpha Vantage
• Yahoo Finance
• Financial Modeling Prep (FMP)
• FRED
• News API
• SEC EDGAR

Tool Catalog (Phase 1 MVP)

• Market
  • get_market_status, get_market_indices, get_vix, get_market_movers, get_sector_performance, get_market_breadth
• Stocks
  • get_stock_price, get_quote, get_company_profile, get_candles, get_stock_news, get_dividends, get_splits, get_earnings_calendar
• Technical
  • get_rsi, get_macd, get_sma, get_ema, get_support_resistance_levels, detect_chart_patterns
• Fundamental
  • get_key_financials, get_financial_statements, get_fundamental_ratings, get_price_targets, get_ownership_signals, get_sec_filings
• Options
  • get_options_chain, get_options_iv, get_options_greeks, get_unusual_options_activity, get_max_pain
• Risk
  • get_beta, get_sharpe_sortino, get_max_drawdown, get_var, get_correlation, get_rebalance_plan, get_markowitz_allocation, get_dividend_projection, get_tax_estimate
• News
  • get_company_news, get_market_news
• Screener
  • run_screener

Environment Variables

Required (at least one external provider recommended):

• FINNHUB_API_KEY
• ALPHAVANTAGE_API_KEY
• FMP_API_KEY
• FRED_API_KEY
• NEWS_API_KEY

Optional:

• YAHOO_FINANCE_ENABLED=true|false (default true)
• SEC_USER_AGENT (default local-stock-analyst/1.0 (support@example.com))
• REQUEST_TIMEOUT_SECONDS (default 15)
• CACHE_TTL_SECONDS (default 60)
• PROVIDER_MIN_INTERVAL_SECONDS (default 0.2)
• TRANSPORT_MODE=auto|stdio|http
• HTTP_TRANSPORT=sse|streamable
• HOST / PORT
• MCP_PATH / HEALTH_PATH

Setup

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Run

Stdio Mode

$env:TRANSPORT_MODE="stdio"
python -m mcp_server

HTTP Mode

$env:TRANSPORT_MODE="http"
$env:HOST="0.0.0.0"
$env:PORT="8000"
python -m mcp_server

Health endpoint defaults to /health.

Tests

python -m pytest -q