blueprint-10k — an MCP server for SEC filing analysis

An MCP server that gives Claude a toolbox of deterministic finance tools for analyzing 10-K/10-Q filings: the LLM does the reading and reasoning, but every number comes from real math in Python — no hallucinated ratios.

Paired with a set of Claude Code subagents (.claude/agents/) that use these tools as a multi-agent equity-research pipeline: retrieve filing → extract financials → analyze risk factors → scout news → forecast → validate → format.

Tools by module

Module	Tools
tools/edgar.py	Fetch filings from SEC EDGAR (company lookup, filing index, section extraction, HTML cleaning)
tools/market_data.py	Prices, history, and market snapshots via yfinance
tools/ratios.py	Liquidity / leverage / profitability / efficiency ratios from raw statement inputs, schema-validated
tools/fcf.py	Free-cash-flow computation
tools/econometrics.py	Regression + time-series diagnostics (statsmodels)
tools/var.py	Value-at-Risk (parametric + historical) for position sizing
tools/options.py	Black-Scholes pricing and greeks
tools/news.py	Multi-source news scout: Alpha Vantage, Finnhub, yfinance, EDGAR 8-Ks, Google News RSS, Reddit — with dedupe, VADER sentiment, and JSON archiving
tools/boilerplate.py	Jaccard-similarity filter that strips boilerplate legalese from risk-factor sections
tools/validation.py	JSON-schema validation + token-aware text chunking
tools/charts.py	Matplotlib chart cards for distribution
tools/output.py	Report assembly + webhook delivery
tools/forecastx.py	Stub: cross-validation against Excel forecasts (xlwings)

Sample news-scout output lives in news_archive/.

Setup

pip install -r requirements.txt
cp .mcp.json.example .mcp.json   # then fix the paths for your machine
mcp run server.py                # or let Claude Code start it via .mcp.json

Optional API keys (each news source degrades gracefully if its key is absent):

Env var	Source
ALPHAVANTAGE_KEY	Alpha Vantage news + sentiment
FINNHUB_KEY	Finnhub company news
REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET	Reddit via PRAW
MAKE_WEBHOOK_INTERNAL / MAKE_WEBHOOK_PUBLIC	Make.com delivery webhooks for tools/output.py

Note: SEC EDGAR requires a User-Agent identifying you (see tools/edgar.py) — replace the contact info with your own before heavy use.

The agent pipeline

.claude/agents/ defines the subagents Claude Code spawns for a full analysis:

• coordinator — orchestrates the run, delegates to the specialists
• filing_retrieval — finds and fetches the right 10-K/10-Q from EDGAR
• financial_extractor — pulls the statements out of Item 8
• risk_analyst — reads Item 1A with the boilerplate filter
• news_scout — recent-news sweep with sentiment
• forecaster — projections grounded in the econometrics tools
• options_strategist — strategy ideas priced with the BS tools
• validator / output_formatter — schema checks, then the final report