# sec-edgar-mcp

An MCP (Model Context Protocol) server that gives natural-language access to
[SEC EDGAR](https://www.sec.gov/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`](plans/architecture.md); the original requirements are
in [`reference/product_spec.md`](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.

## Tools

| Tool | What it does |
|---|---|
| `resolve_company` | Ticker or company name → canonical CIK, with explicit multi-candidate disambiguation when ambiguous |
| `list_filings` | A company's filings by form type and date range (metadata only — accession numbers, dates, form types) |
| `get_filing_section` | One named 10-K section (Business, Risk Factors, Properties, Legal Proceedings, Cybersecurity, Unresolved Staff Comments, Mine Safety Disclosures, MD&A), paginated |
| `get_financial_facts` | XBRL-sourced figures — revenue, net income, assets, and similar line items — for a company, annual (10-K) or quarterly (10-Q), grounded per value in the filing that reported it |
| `compare_filing_sections` | Structured added/removed/changed blocks between the same section across two 10-Ks — never a character diff |
| `list_insider_transactions` | Form 4 insider transactions for a company or person, value-sorted, filterable by transaction code and date range |

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`](https://docs.astral.sh/uv/).

```bash
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:

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

Run it:

```bash
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

```bash
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:

```bash
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

```bash
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
```