sec-edgar-mcp

An MCP (Model Context Protocol) server that gives natural-language access to SEC EDGAR filings — company lookups, filing content, financial-statement figures, insider transactions, and filing-to-filing comparisons — over streamable HTTP, so any MCP client (Claude Code, Claude Desktop, etc.) can answer real filing-research questions grounded in real filings, not general knowledge.

Built as a portfolio piece demonstrating production-minded engineering around a public, rate-limited, unauthenticated API: a shared two-tier rate limiter, a coalescing cache, real-data-validated HTML/XML parsing, and a tool surface shaped by testing against a real LLM client, not just unit tests. The full design reasoning — and the tradeoffs behind it — lives in plans/architecture.md; the original requirements are in reference/product_spec.md.

Status: functionally complete through Milestone 7 (all 6 tools, tested against real EDGAR data and a real MCP client). Not yet deployed — this repo runs as a local server today; containerized deployment is Milestone 8.

Why HTTP, not stdio

SEC EDGAR requires a compliant User-Agent with contact info and enforces a per-IP rate limit (~10 req/s). Under stdio, every user's local process is its own uncoordinated IP — the rate limit is never actually exercised or enforced. Under HTTP, one deployment means one egress IP, one shared budget, and one place to get compliance, rate limiting, and caching right. That decision — and everything it forces (single-process invariant, global 429 backoff, cache design) — is spelled out in plans/architecture.md's Decision 0.

Related MCP server: SEC EDGAR MCP

Tools

Each tool's docstring is deliberately prescriptive about when to call it and what it doesn't cover — see src/sec_edgar_mcp/server/tools.py. The server's top-level instructions (in src/sec_edgar_mcp/server/app.py) state the full current scope boundary up front, so a client learns what's out of scope before trying a tool, not after a failed attempt.

Explicitly out of scope today (see reference/product_spec.md §7 for the full list and why): executive compensation (DEF 14A tables), 10-Q prose sections like a quarterly MD&A, 8-K event-type summarization, cross-company/ full-text search, and beneficial ownership above 5% (Schedule 13D/13G).

Quickstart

Requires Python 3.14+ and uv.

uv sync

SEC EDGAR requires a compliant User-Agent — the server fails fast at startup without one, rather than failing silently on the first request:

export SEC_EDGAR_USER_AGENT="your-app-name/0.1 (you@example.com)"

Run it:

uv run python -m sec_edgar_mcp

Starts a streamable-HTTP server on 127.0.0.1:8000 (configurable via SEC_EDGAR_HOST / SEC_EDGAR_PORT; see src/sec_edgar_mcp/config.py for every other tunable — rate limits, cache TTLs, retry/backoff — all have defaults, only the User-Agent is required).

Try it with MCP Inspector

uv run mcp dev src/sec_edgar_mcp/__main__.py

Opens a browser UI for calling each tool directly with raw JSON-RPC — good for verifying an individual tool's input/output shape, not for testing how an LLM actually selects between tools.

Connect it to Claude Code

With the server running:

claude mcp add --transport http sec-edgar-mcp http://127.0.0.1:8000/mcp

Start a new claude session (MCP servers load at session startup) and ask it a real question — e.g. "Has Apple's risk factor language around supply chain changed in the last two 10-Ks?" or "Show me every Form 4 insider sale by Nvidia executives in the last 90 days, sorted by value."

Development

uv run pytest          # unit + tool-layer tests (mocked EDGAR, no network)
uv run pytest -m live  # opt-in tests against real EDGAR
uv run ruff check .
uv run ruff format .
uv run mypy --strict src tests

Four tiers of automated tests, plus a fifth manual one — connecting the running server to a real MCP client and asking it natural-language questions — which is what actually found several of the bugs fixed in this repo's history (see plans/architecture.md's Testing section and recent commit messages for specifics). tests/fixtures/filings/ holds ~10 real, committed 10-K and Form 4 filings across filer sizes and eras — the parsers are validated against real data, not synthetic HTML.

Project layout

src/sec_edgar_mcp/
  config.py        # required SEC_EDGAR_USER_AGENT, everything else defaulted
  domain/           # Pydantic models (CIK, Filing, InsiderTransaction, FinancialFact, ...)
  edgar/            # rate limiter, cache, HTTP client, endpoint wrappers, parsers
  services/         # composition logic (resolve, compare, insiders, financials)
  server/           # MCPServer, @mcp.tool() adapters, logging, scope instructions
tests/
  fixtures/filings/ # ~10 real, committed SEC filings
plans/architecture.md    # full design reasoning and milestone history
reference/product_spec.md # original requirements + recorded scope decisions