EdgarMCP

PyPI License: MIT

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).