sec-engine 0.7.0

LLM-optimized SEC EDGAR MCP server

sec-engine

LLM-optimized SEC EDGAR MCP server. Provides nine tools that wrap the SEC's public JSON APIs for financial data extraction and analysis — no authentication required.

Tools

Tool	Purpose
resolve	Ticker/CIK to company identity (name, SIC, exchanges, fiscal year end)
filings	List SEC filings with form type and date filtering
search_filings	Full-text search across every filer, 2001-present
snapshot	Latest key metrics (~20) + full XBRL concept index
concept_history	Time series for one XBRL metric across all filings
cross_company	Compare one metric across ALL filers for peer/sector screening
filing_section	Extract narrative text from 10-K/10-Q Items (MD&A, Risk Factors, etc.)
filing_documents	List every file in a filing's archive directory
filing_document	Read any file in any filing, of any form type

Reaching filings that aren't 10-K/10-Q

filing_section parses Item N headers, so it only works on Item-structured filings. Everything else — Form 144, Form 4, N-CSR, 424B3, DEF 14A, exhibits — goes through filing_document, which dispatches on file type:

• XML (Form 144, Forms 3/4/5) parses into nested structured data. Repeated rows such as a Form 144's Table II become arrays.
• HTML is stripped to clean text.

Prospectuses and N-CSRs routinely exceed 5 MB. Pass contains= to jump straight to a phrase and get context windows back, rather than paging through the document with offset=.

Some filers submit a PDF converted to HTML — each page a background image with every word absolutely positioned over it. Such a document has no tables and no reading order in its markup, so filing_document detects the layout and rebuilds the order from the coordinates, marking column breaks with |. Without this, figures shred into their digits and columns are lost. Detection is structural and conventional filings are unaffected.

When the filer differs from the issuer — as it does for Form 144 and Form 4 — the filing won't appear under the issuer in filings(). Use search_filings, which returns the archive_cik and document name needed to fetch it.

Installation

pip install sec-engine

Or with uv:

uv pip install sec-engine

Usage

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "sec-engine": {
      "command": "sec-engine"
    }
  }
}

Docker Compose

Edit SEC_EDGAR_USER_AGENT in compose.yml with your name and email, then:

docker compose up --build

Direct (stdio)

sec-engine

Direct (streamable HTTP)

SEC_ENGINE_TRANSPORT=streamable-http sec-engine

The server supports both stdio and streamable HTTP transports via the Model Context Protocol.

Configuration

All configuration is via environment variables:

Variable	Default	Description
SEC_EDGAR_USER_AGENT	SEC-Engine/0.1 (sec-engine-mcp)	User-Agent sent to SEC.gov (SEC requires a descriptive UA)
SEC_ENGINE_TRANSPORT	stdio	Transport protocol: stdio or streamable-http
SEC_ENGINE_HOST	127.0.0.1	Listen address (streamable-http only)
SEC_ENGINE_PORT	8000	Listen port (streamable-http only)
SEC_ENGINE_PATH	/mcp	HTTP endpoint path (streamable-http only)
SEC_ENGINE_ALLOWED_HOSTS		Comma-separated allowed hosts for DNS rebinding protection (e.g. *)

Requirements

• Python >= 3.11

Disclaimer

This software retrieves publicly available data from the SEC EDGAR system. It is provided as-is for informational purposes only and does not constitute financial, legal, or investment advice. The authors are not responsible for how you use this data or any consequences arising from its use. You are solely responsible for complying with all applicable SEC policies, regulations, and terms of service.

License

MIT