Metadata-Version: 2.4
Name: sec-engine
Version: 0.5.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>=1.0.0
Description-Content-Type: text/markdown

# sec-engine

LLM-optimized SEC EDGAR MCP server. Provides six 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 |
| `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 sections (MD&A, Risk Factors, etc.) |

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