# SEC EDGAR MCP

A free, key-less [Model Context Protocol](https://modelcontextprotocol.io) server for
**SEC EDGAR** — company filings, XBRL financial facts, and full-text search, straight from
the primary source. No API key, no account, no rate-limited third-party wrapper.

Built with [FastMCP](https://github.com/jlowin/fastmcp).

## Tools

| Tool | What it does |
| --- | --- |
| `edgar_status` | Show configuration (User-Agent, endpoints) and check that SEC is reachable. |
| `lookup_cik` | Resolve a stock ticker to its SEC CIK number and company name. |
| `company_filings` | Recent filings for a company (ticker or CIK), filterable by form type (`10-K`, `8-K`, `4`, ...). |
| `insider_transactions` | Recent insider Form 4 / 4-A filings for a company. |
| `company_concept` | Time series for one XBRL concept, e.g. `NetIncomeLoss`, `Assets`, `EarningsPerShareDiluted`. |
| `company_facts` | Discover every XBRL concept tag a company reports (feed tags into `company_concept`). |
| `company_financials` | Headline snapshot: revenue, net income, assets, liabilities, equity, diluted EPS. |
| `full_text_search` | Full-text search across all EDGAR filings (2001-present), with form and date filters. |

All filing results include direct links to the documents on SEC.gov.

## Install

```bash
git clone https://github.com/jsconiers/sec-edgar-mcp.git
cd sec-edgar-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python test_edgar.py   # offline tests
```

## Use with Claude Desktop

Add to `claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "sec-edgar": {
      "command": "/absolute/path/to/sec-edgar-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/sec-edgar-mcp/sec_edgar_mcp.py"]
    }
  }
}
```

Restart Claude Desktop, then ask things like *"Pull NVIDIA's latest 10-K"*, *"What was Apple's
net income trend?"*, or *"Find recent 8-Ks mentioning artificial intelligence."*

## Examples

```
lookup_cik("AAPL")                          -> CIK 0000320193, Apple Inc.
company_filings("NVDA", form_type="10-K")   -> recent annual reports + links
insider_transactions("MSFT")                -> recent Form 4 insider activity
company_concept("AAPL", "NetIncomeLoss")    -> quarterly/annual net income series
company_financials("TSLA")                  -> revenue, net income, assets, equity, EPS
full_text_search("data breach", forms="8-K", date_from="2025-01-01")
```

## Data sources

- `data.sec.gov` — submissions (filing history) and XBRL company facts / concepts
- `efts.sec.gov` — EDGAR full-text search
- `www.sec.gov/files/company_tickers.json` — ticker -> CIK map

## Access note (User-Agent)

SEC asks API clients to identify themselves with a contact in the `User-Agent`. In practice the
`www.sec.gov` host currently sits behind a bot manager that **rejects** descriptive User-Agents,
so this server sends a browser-like header set that works. Override it via the `SEC_EDGAR_UA`
environment variable if you wish (a browser-like UA is recommended). Please keep request volume
under ~10 requests/second per SEC's fair-access policy.

## License

MIT — see [LICENSE](LICENSE). Not affiliated with or endorsed by the U.S. Securities and
Exchange Commission. For informational purposes only; not investment advice.