edgarmcp

MCP server for SEC EDGAR. 5 tools, zero infrastructure. Resolves everything in real-time against EDGAR + XBRL.

• get_filings — Discover filings, press releases, contracts, and notes

• read_document — Read filings, sections, exhibits, or notes as Markdown

• search_filings — BM25 search across filings, attachments, and notes

• view_financials — XBRL statements with Q4 inference, YTD normalization, stock splits, TTM

• search_edgar — Full-text search across all of EDGAR (SEC EFTS)

Key features

• Multi-period financials — Pull 8 quarters or 3 years in one call. Q4 inferred, YTD normalized, stock splits adjusted, TTM computed.

• Everything is addressable — Sections, press releases, exhibits, and notes are individually discoverable, readable, and searchable.

• Clickable citations — Results link to the exact element in the original SEC filing HTML. Click to open, highlight, and scroll to source.

• High-fidelity parsing — Powered by sec2md. Tables, sections, iXBRL tags, and page structure preserved.

• Two-stage search — Broad discovery across all EDGAR via EFTS, then deep BM25 search within specific filings.

• Persistent cache — Parsed filings, company metadata, and XBRL statements cached to disk (or S3) so repeat queries are instant, even across restarts.

• Remote deployment — One-click deploy to Railway with API key auth, health checks, and remote citations.

Quick Start

Install from PyPI

pip install mcp-sec-edgar

Or install from source:

git clone https://github.com/lucasastorian/edgarmcp.git
cd edgarmcp
pip install -e .

Claude Code

claude mcp add edgarmcp -- env EDGAR_IDENTITY="Your Name your@email.com" edgarmcp

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "edgarmcp": {
      "command": "edgarmcp",
      "env": {
        "EDGAR_IDENTITY": "Your Name your@email.com"
      }
    }
  }
}

If installed from source with uv:

{
  "mcpServers": {
    "edgarmcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/edgarmcp", "run", "edgarmcp"],
      "env": {
        "EDGAR_IDENTITY": "Your Name your@email.com"
      }
    }
  }
}

Restart Claude Desktop. edgarmcp should appear as an MCP server.

Transport

edgarmcp                            # stdio (default)
edgarmcp --http --port 8000         # streamable HTTP (localhost)
edgarmcp --http --host 0.0.0.0     # public HTTP (auto-generates API key)
edgarmcp --no-citations             # disable citation tags

EDGAR Identity

The SEC requires a User-Agent header identifying who is making requests. Set the EDGAR_IDENTITY environment variable to your name and email:

export EDGAR_IDENTITY="Your Name your@email.com"

Related MCP server: secfinapi-mcp

Remote Deployment (Railway)

Deploy edgarmcp as a remote MCP server on Railway with one click.

Setup

1. Fork/clone the repo and connect it to Railway

2. Set environment variables in Railway:

3. Railway builds from the included Dockerfile and deploys with /health healthcheck

Auth

When binding to 0.0.0.0 (all remote deployments), an API key is always required:

• Set EDGARMCP_API_KEY explicitly, or

• One is auto-generated on startup and printed to logs

Clients authenticate with Authorization: Bearer <key>. The /health, /cite/, and /filing/ endpoints are public (SEC filings are public data).

Persistent Cache

Parsed filings, company metadata, and XBRL statements are cached persistently so expensive SEC fetches and parses happen once:

Local: stored at ~/.edgarmcp/cache/ (default, zero-config).

S3-compatible (Railway Storage Buckets): set these env vars to use S3 instead of filesystem:

Citations

Citations work remotely — filing HTML is served through the main HTTP port at /cite/ and /filing/. Set EDGARMCP_BASE_URL to your deployment URL so citation links resolve correctly for remote clients.

Connecting a Remote MCP Client

claude mcp add edgarmcp-remote --transport http https://edgarmcp-production.up.railway.app/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Tools

get_filings

Discover a company's SEC filings, attachments, and notes — all as a flat document list. Combines company lookup, filing listing, attachment listing, and notes listing in a single tool.

Supported forms: 10-K, 10-Q, 8-K, 20-F, 6-K, DEF 14A, S-1, SC 13D, SC 13G, Form 4. Attachment types include press releases, investor presentations, material contracts, merger agreements, debt instruments, charter/bylaws, and more.

read_document

Unified reader — one tool for main filings, sections, press releases, exhibits, and notes. Route by parameter:

First read of any filing returns a navigation header with sections, notes, and attachments — the LLM uses these to decide where to go next.

Section extraction covers 10-K, 10-Q, 8-K, and 20-F.

search_filings

BM25 search across a company's filings, attachments, and notes. Resolves filings internally, loads and parses them, chunks everything, and ranks by BM25.

Searches main filing pages, notes, and high-value attachments (press releases, investor presentations, material contracts, etc.) by default.

view_financials

Pull financial statements from XBRL with full period merging.

Under the hood: loads XBRL from filings, extracts statement DataFrames, then runs Q4 inference (FY - Q1 - Q2 - Q3), YTD normalization (converting 6M/9M data to individual quarters), stock split adjustment, and TTM computation. Returns a clean Markdown table with the notes index from the source filings so the LLM can immediately dig into accounting details.

search_edgar

Full-text search across the entire EDGAR corpus using SEC EFTS.

The discovery tool. Search all of EDGAR without knowing which companies to look at. Pipe results into read_document or search_filings for deeper analysis.

Design Decisions

5 tools, maximum coverage. Company lookup, filing listing, attachment listing, and notes listing are consolidated into get_filings. Filing, attachment, and note reading are unified in read_document. Minimum surface area for the LLM.

Two-level cache. L1 is an in-memory LRU (~20 filings) for instant re-reads within a session. L2 is persistent (filesystem or S3) so parsed filings survive restarts and can be shared across instances. SEC filings are immutable — no TTL needed.

BM25 over embeddings. Pure Python, no GPU or API needed. Good enough for keyword-heavy SEC filings. SEC EFTS covers cross-corpus discovery.

Limitations

• No embedding search — BM25 only. Mitigated by SEC EFTS for cross-corpus discovery.

• Cold start per filing — First read requires download + parse (~2-5s). Subsequent reads cached (persistent across restarts).

• SEC rate limits — 10 requests/second. Parallel loading respects this via edgartools-async.

• XBRL availability — view_financials requires XBRL (10-K/10-Q/20-F, generally available since ~2009).

• No market data — No price or market cap context.

• Memory — Each cached filing ~1-5MB. 20 filings in L1 = 20-100MB.

• view_financials latency — Loading XBRL for 4-8 filings takes ~5-15s on first call.

Dependencies

edgartools-async, sec2md, mcp (FastMCP), rank-bm25, pydantic, pandas

License

Apache 2.0 — see LICENSE for details.