Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<!-- mcp-name: io.github.birthday-tools/edgarmcp -->
EdgarMCP
An MCP server that gives AI agents clean, normalized access to financial data: company fundamentals and insider trades from SEC EDGAR, macro series from FRED, 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
pip install mcp-edgarThis installs the edgarmcp console script (a stdio MCP server).
Quick start
Add it to an MCP client. For Claude Desktop (claude_desktop_config.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: [email protected]) |
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. Real-time quotes come from Tradernet's public anonymous WebSocket feed. CUSIP/ISIN → ticker mapping uses OpenFIGI (Bloomberg; free tier, 25 req/min anonymous, 250 req/min with a key).
License
MIT © 2026 birthday.tools