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 [email protected]" 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 [email protected]"
      }
    }
  }
}

If installed from source with uv:

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

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 [email protected]"

---

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:

Variable	Required	Description
EDGAR_IDENTITY	yes	"Your Name [email protected]"
EDGARMCP_API_KEY	no	Bearer token for auth (auto-generated if not set)
EDGARMCP_BASE_URL	no	Your deployment URL for citation links (e.g. https://edgarmcp-production.up.railway.app)

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:

Layer	Key	What
Companies	companies/{id}.json.gz	Ticker/CIK/name mapping
Parsed filings	parsed/{accession}.json.gz	Full sec2md parse (pages, sections, notes, attachments)
XBRL statements	xbrl/{accession}/{statement}.json.gz	Extracted financial data per filing

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

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

Variable	Description
BUCKET	Bucket name
ACCESS_KEY_ID	S3 access key
SECRET_ACCESS_KEY	S3 secret key
ENDPOINT	S3 endpoint URL
REGION	AWS region (default: us-east-1)

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.

Parameter	Type	Required	Description
company	str	yes	Ticker, company name, or CIK
forms	list[FormType]	no	Filter by form type (default: major forms)
attachment_types	list[AttachmentType]	no	Filter to specific attachment types
include_notes	bool	no	Include notes to financial statements
start_date / end_date	str	no	YYYY-MM-DD date range (default: last 2 years)
limit	int	no	Max documents returned (default: 20, max: 100)

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:

Parameter	Type	Required	Description
accession_number	str	yes	Filing accession number
section	SectionType	no	Specific section (e.g. "risk_factors", "mda")
exhibit_number	str	no	Exhibit to read (e.g. "99.1")
note_name	str	no	Note to read (e.g. "note_2")
start_page / end_page	int	no	Page range (max 20 pages per request)

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.

Parameter	Type	Required	Description
query	str	yes	Search query
company	str	yes*	Ticker/name/CIK (*or provide accession_numbers)
forms	list[FormType]	yes*	Form types to search
sections	list[SectionType]	no	Scope to specific sections
attachment_types	list[AttachmentType]	no	Search only these attachment types
xbrl_tags	list[str]	no	Filter to chunks containing XBRL concept tags
accession_numbers	list[str]	no	Search explicit filings directly
limit	int	no	Max filings to load (default: 5, max: 10)
top_k	int	no	Results to return (default: 10, max: 25)

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.

Parameter	Type	Required	Description
symbol	str	yes	Ticker symbol
statement_type	StatementType	yes	income_statement, balance_sheet, or cash_flow
report_type	ReportType	yes	annual, quarterly, or ttm
periods	int	no	Number of periods (default: 4, max: 8)

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.

Parameter	Type	Required	Description
query	str	yes	Full-text query (supports boolean operators)
entity	str	no	Company name or CIK to scope the search
forms	list[FormType]	no	Filter by form type
start_date / end_date	str	no	YYYY-MM-DD
limit	int	no	Max results (default: 10, max: 50)

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.