io.github.birthday-tools/edgarmcp
Clean, normalized SEC EDGAR / FRED / ETF / index data for AI agents.
Open source Open in the app JSON README (API)
About
Clean, normalized SEC EDGAR / FRED / ETF / index data for AI agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- birthday-tools
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Last push
- 2026-06-29T01:46:16Z
- Repository state
- sumiu
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:31
- Updated
- 2026-08-29 03:02:31
- Origin id
io.github.birthday-tools/edgarmcp
README
<!-- mcp-name: io.github.birthday-tools/edgarmcp -->
# EdgarMCP
[](https://pypi.org/project/mcp-edgar/)
[](LICENSE)
[](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml)
An MCP server that gives AI agents clean, normalized access to financial data:
company fundamentals and insider trades from [SEC EDGAR](https://www.sec.gov/edgar),
macro series from [FRED](https://fred.stlouisfed.org/), real-time quotes via the
Tradernet WebSocket feed, ETF/fund holdings from SEC NPORT-P, look-through analytics,
and index snapshots.
Raw sources (XBRL, bulky filing HTML, ownership XML) are expensive and error-prone for
agents — they burn tokens and trip up on parsing. EdgarMCP returns agent-ready JSON.
## Installation
```bash
pip install mcp-edgar
```
This installs the `edgarmcp` console script (a stdio MCP server).
## Quick start
Add it to an MCP client. For Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"edgarmcp": {
"command": "edgarmcp",
"env": {
"FRED_API_KEY": "your-free-fred-key",
"OPENFIGI_API_KEY": "optional-openfigi-key"
}
}
}
}
```
Both keys are optional: without `FRED_API_KEY` the FRED-backed tools degrade gracefully;
without `OPENFIGI_API_KEY` holding resolution runs in anonymous mode.
## Tools
| Tool | Purpose |
|---|---|
| `get_company_facts(ticker)` | Normalized fundamentals (revenue, EPS, margins, debt) |
| `get_financial_statement(ticker, statement, period)` | Income/balance/cashflow as structured JSON |
| `get_filings(ticker, form_type, limit)` | Recent SEC filings (10-K/10-Q/8-K) with metadata and document URLs |
| `parse_filing_section(url, section)` | Extract a 10-K section (Risk Factors, MD&A) as clean text |
| `get_insider_trades(ticker, limit)` | Form 3/4/5 insider transactions (who, role, buy/sell, volume) |
| `get_macro_series(series_id, start, end)` | FRED macro series (rates, inflation, unemployment) with metadata |
| `get_quote(ticker)` | Real-time L1 quote (last/bid/ask/volume) via the Tradernet WebSocket feed |
| `get_etf_holdings(ticker, limit)` | ETF/fund holdings (top by weight) + AUM, NAV, asset/country mix from SEC NPORT-P |
| `get_holdings_analysis(symbol, limit)` | Look-through of an ETF/index: sector breakdown + weighted net-margin/ROE with coverage |
| `get_index(index)` | Index snapshot (S&P 500, NASDAQ-100, Dow, NASDAQ Composite): level from FRED, tracking ETF, holdings preview |
## Configuration
| Variable | Description | Default |
|---|---|---|
| `EDGAR_USER_AGENT` | User-Agent for SEC requests | `EdgarMCP/0.1 (contact: info+sec@birthday.tools)` |
| `EDGAR_RATE_LIMIT` | Requests per second | `10` |
| `EDGAR_CACHE_DIR` | File cache directory | `edgar_cache` |
| `FRED_API_KEY` | Free FRED key for `get_macro_series` / index levels | — |
| `OPENFIGI_API_KEY` | Optional OpenFIGI key for higher CUSIP/ISIN rate limit | — |
| `EDGAR_TELEMETRY` | Enable anonymous opt-in usage telemetry (`1`/`true`/`yes`/`on`) | off |
| `EDGAR_TELEMETRY_URL` | Telemetry endpoint (only used when telemetry is enabled) | `https://t.birthday.tools/v1/events` |
Variables are read from the environment; locally you can put them in a `.env` file.
## Telemetry
Telemetry is **opt-in and off by default**. Enable it by setting `EDGAR_TELEMETRY=1`.
When enabled, the server periodically sends an anonymous, aggregated payload:
- a random install id (generated once, stored locally),
- the package version, Python minor version (e.g. `3.12`), and OS (`darwin`/`linux`/`windows`),
- per-tool call counts and per-tool error counts.
It **never** sends request content — no tickers, arguments, results, error messages, IP
addresses, file paths, or environment. Sending is fire-and-forget and never blocks or
breaks a tool call. Override the endpoint with `EDGAR_TELEMETRY_URL`, or leave telemetry
disabled (the default) to send nothing.
## Architecture
Three isolated layers: a platform-independent **data layer** (HTTP client with a host
allowlist, ticker/name/CUSIP/ISIN resolution, XBRL normalizers, filing/ownership/NPORT-P
parsers, FRED, the Tradernet WebSocket client, OpenFIGI identifier mapping, look-through
and index analytics); a **cache layer** (aggressive caching of immutable filings and FIGI
mappings; mutable FRED series are not cached); and a thin **MCP layer**. The data layer
knows nothing about MCP and ports unchanged between a marketplace and self-hosting.
## Security
- Outbound requests are restricted to an HTTPS host allowlist (SSRF defense), centralized
across all sources (SEC, FRED, OpenFIGI).
- Ownership and NPORT XML is parsed with `defusedxml` (XXE / billion-laughs defense).
- Secrets (FRED / OpenFIGI keys) are redacted from error messages and never placed in URLs
or cache keys.
- Real-time quotes come from Tradernet's public anonymous WebSocket feed
(`wss://wss.tradernet.com/`); a dedicated client with a hardcoded URL.
- CUSIP/ISIN holding resolution goes through OpenFIGI (`api.openfigi.com`, allowlisted);
on failure it falls back to name matching.
## Data licenses
SEC EDGAR data is public domain, used with a descriptive `User-Agent` and the 10 req/s
limit. FRED data is provided by the Federal Reserve Bank of St. Louis under its
[terms of use](https://fred.stlouisfed.org/legal/). Real-time quotes come from Tradernet's
public anonymous WebSocket feed. CUSIP/ISIN → ticker mapping uses
[OpenFIGI](https://www.openfigi.com/) (Bloomberg; free tier, 25 req/min anonymous,
250 req/min with a key).
## License
[MIT](LICENSE) © 2026 birthday.tools