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

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):

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