# edgar-mcp

Model Context Protocol (MCP) server for the **SEC EDGAR data APIs** on [data.sec.gov](https://data.sec.gov).

No API key is required. The SEC asks that automated clients declare a descriptive **User-Agent** (with contact email) and stay under **10 requests/second**.

Official docs: [EDGAR Application Programming Interfaces](https://www.sec.gov/search-filings/edgar-application-programming-interfaces)

## Features

| Tool | Description |
|------|-------------|
| `lookup_company` | Search tickers / names / CIKs |
| `get_company_info` | Entity metadata (SIC, addresses, fiscal year end, …) |
| `get_filings` | Recent (and optional historical) filings with form/date filters |
| `get_filing_documents` | Document list + URLs for a specific accession |
| `list_company_facts` | Discover XBRL taxonomies and concept tags for a company |
| `get_company_concept` | Time series for one XBRL concept (e.g. us-gaap Assets) |
| `get_xbrl_frames` | Cross-company frame for a concept/period |
| `get_bulk_data_info` | Nightly bulk ZIP URLs and fair-access notes |

## Requirements

- Node.js 18+

## Setup

```bash
npm install
npm run build
```

Set your identity (required by the SEC):

```bash
export EDGAR_USER_AGENT="YourName your.email@example.com"
```

(`SEC_USER_AGENT` is accepted as an alias.)

## Run

```bash
npm start
# or
node dist/index.js
```

### Claude Desktop / Cursor / MCP clients

Add to your MCP config (example for Claude Desktop):

```json
{
  "mcpServers": {
    "edgar": {
      "command": "node",
      "args": ["/absolute/path/to/edgar-mcp/dist/index.js"],
      "env": {
        "EDGAR_USER_AGENT": "YourName your.email@example.com"
      }
    }
  }
}
```

Development (no build step):

```bash
npx tsx src/index.ts
```

## API coverage

Maps to the public RESTful APIs:

- **Submissions** — `https://data.sec.gov/submissions/CIK##########.json`
- **Company facts** — `https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json`
- **Company concept** — `https://data.sec.gov/api/xbrl/companyconcept/CIK##########/{taxonomy}/{tag}.json`
- **Frames** — `https://data.sec.gov/api/xbrl/frames/{taxonomy}/{tag}/{unit}/{period}.json`
- **Ticker map** — `https://www.sec.gov/files/company_tickers_exchange.json`
- **Filing directories** — `https://www.sec.gov/Archives/edgar/data/{cik}/{accession}/index.json`

Period formats for frames: `CY2019` (annual), `CY2019Q1` (quarterly duration), `CY2019Q1I` (instantaneous). Units with numerator/denominator use `-per-` (e.g. `USD-per-shares`).

## Fair access

This server:

1. Sends a configurable `User-Agent` on every request
2. Rate-limits to ~9 requests/second (under the SEC’s 10 rps cap)
3. Caches the company ticker map for 24 hours

Please do not raise the rate for bulk scraping; use the [nightly bulk ZIPs](https://www.sec.gov/search-filings/edgar-application-programming-interfaces) instead (`get_bulk_data_info`).

## Example prompts

- “Look up NVIDIA’s CIK and latest 10-K.”
- “What was Apple’s AccountsPayableCurrent over the last few years?”
- “List us-gaap tags for Microsoft that contain Revenue.”
- “Show CY2023 Q4 instantaneous Assets for USD across filers (first 20).”
- “Documents in accession 0000320193-25-000079 for Apple.”

## License

MIT. EDGAR data is public domain U.S. government work; reuse is free under SEC dissemination policy.