edgarmcp

<!-- 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-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):

{
  "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. 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