Metadata-Version: 2.4
Name: sec-engine
Version: 0.7.0
Summary: LLM-optimized SEC EDGAR MCP server
Author-email: taika-st <taika-st@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp<2,>=1.26.0
Description-Content-Type: text/markdown

# 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

```bash
pip install sec-engine
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install sec-engine
```

## Usage

### Claude Desktop

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

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

### Docker Compose

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

```bash
docker compose up --build
```

### Direct (stdio)

```bash
sec-engine
```

### Direct (streamable HTTP)

```bash
SEC_ENGINE_TRANSPORT=streamable-http sec-engine
```

The server supports both stdio and [streamable HTTP](https://modelcontextprotocol.io/) transports via the [Model Context Protocol](https://modelcontextprotocol.io/).

## 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