Local Stock Analyst MCP (Python)

MCP server for stock intelligence workflows with:

• Domain-split tool registry (market, stocks, technical, fundamental, options, risk, news, screener, portfolio)

• Multi-provider adapters with fallback routing

• In-memory TTL caching and per-provider rate-limit guards

• stdio and Render-compatible HTTP transport modes

MCP Prompts and Resources

The server now exposes MCP prompts/resources in addition to tools.

• Prompt: portfolio_analysis

  • Arguments: required portfolio (string)

  • Purpose: builds a structured institutional-grade portfolio analysis instruction

• Resource: portfolio://current

  • MIME type: application/json

  • Purpose: returns the latest successful portfolio workflow snapshot payload

  • Note: run a portfolio workflow first (for example analyze_portfolio_excel) to populate it

Prompt examples

• List prompts (prompts/list) now includes portfolio_analysis.

• Get prompt (prompts/get) request example:

{
  "name": "portfolio_analysis",
  "arguments": {
    "portfolio": "US Core"
  }
}

• Example behavior:

  • Unknown prompt name -> invalid-params style error (Unknown prompt: ...)

  • Missing required argument -> invalid-params style error (Missing required arguments: ...)

Resource examples

• List resources (resources/list) now includes portfolio://current.

• List resource templates (resources/templates/list) now includes portfolio://snapshot/{report_type}.

• Read resource (resources/read) request example:

{
  "uri": "portfolio://current"
}

• Example successful response content is JSON with:

  • uri, report_type, source_file_path, payload

• Error behavior:

  • Invalid URI / unknown resource -> not found style error

  • No snapshot yet -> safe not-found message without sensitive token/key leakage

  • Resource not found maps to JSON-RPC code -32002

Capability and subscription behavior

• prompts capability advertises listChanged: true.

• resources capability advertises:

  • subscribe: true

  • listChanged: true

• Resource subscriptions are supported via resources/subscribe and resources/unsubscribe.

• Subscribed clients receive notifications/resources/updated when portfolio://current is refreshed by portfolio workflows.

Provider Support

• Finnhub

• Alpha Vantage

• Yahoo Finance

• Financial Modeling Prep (FMP)

• TwelveData

• MarketStack

• Web quote fallback search

• 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, get_news_sentiment_overview, get_macro_risk_news

• Portfolio News Impact

  • get_portfolio_news_impact, get_symbol_news_impact, get_watchlist_news_impact

• Screener

  • run_screener

• Portfolio

  • validate_portfolio_excel, analyze_portfolio_excel, portfolio_benchmark_report, portfolio_stress_test

Portfolio Excel Format

The portfolio module expects these exact columns in .xlsx/.xls:

• Symbol

• Bucket (Core|Growth|Defensive|Income|Speculative)

• Quantity (positive integer)

• Entry_Price (numeric)

• Target_Weight (decimal like 0.15)

Validation rules:

• Required columns must exist

• No null values in required columns

• All symbols must be valid US ticker format

• Target_Weight sum must equal 1.0 +/- 0.01

Example file path input:

• C:/Users/LENOVO/Downloads/Sample_US_Portfolio_MCP_Format.xlsx

Environment Variables

Required (at least one external provider recommended):

• FINNHUB_API_KEY

• ALPHAVANTAGE_API_KEY

• FMP_API_KEY

• TWELVEDATA_API_KEY

• MARKETSTACK_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

• CLAUDE_API_KEY (or ANTHROPIC_API_KEY) for AI portfolio executive summaries

• CLAUDE_MODEL (or ANTHROPIC_MODEL), default claude-sonnet-4-5-20250929

• PORTFOLIO_ENABLE_AI_SUMMARY=true|false (default true)

Stock Tool JSON Responses

All tools in the stocks domain now return strict JSON strings:

• Success example:

{"source":"Alpha Vantage","data":{"symbol":"AAPL","price":210.5,"change":1.2,"percent_change":0.57,"high":211.0,"low":208.2,"open":209.4,"previous_close":209.3,"timestamp":1700000000,"source":"alphavantage"}}

• Failure example (shared for all stock-domain tools when fallback is exhausted):

{"error":"All stock data providers are currently unavailable. Please try again later."}

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

Protocol coverage now includes prompt/resource list/get/read success and error paths in tests/test_mcp_prompts_resources.py.

Canonical Runtime Package

Use mcp_server/ as the only supported runtime package and entrypoint:

• Run with python -m mcp_server

• Deploy using mcp_server module paths

Resources/ is legacy/reference and is not maintained for new MCP prompt/resource capabilities.