{
  "markdown": "<!-- mcp-name: io.github.birthday-tools/edgarmcp -->\n# EdgarMCP\n\n[![PyPI](https://img.shields.io/pypi/v/mcp-edgar.svg)](https://pypi.org/project/mcp-edgar/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/birthday-tools/edgarmcp/actions/workflows/ci.yml)\n\nAn MCP server that gives AI agents clean, normalized access to financial data:\ncompany fundamentals and insider trades from [SEC EDGAR](https://www.sec.gov/edgar),\nmacro series from [FRED](https://fred.stlouisfed.org/), real-time quotes via the\nTradernet WebSocket feed, ETF/fund holdings from SEC NPORT-P, look-through analytics,\nand index snapshots.\n\nRaw sources (XBRL, bulky filing HTML, ownership XML) are expensive and error-prone for\nagents — they burn tokens and trip up on parsing. EdgarMCP returns agent-ready JSON.\n\n## Installation\n\n```bash\npip install mcp-edgar\n```\n\nThis installs the `edgarmcp` console script (a stdio MCP server).\n\n## Quick start\n\nAdd it to an MCP client. For Claude Desktop (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"edgarmcp\": {\n      \"command\": \"edgarmcp\",\n      \"env\": {\n        \"FRED_API_KEY\": \"your-free-fred-key\",\n        \"OPENFIGI_API_KEY\": \"optional-openfigi-key\"\n      }\n    }\n  }\n}\n```\n\nBoth keys are optional: without `FRED_API_KEY` the FRED-backed tools degrade gracefully;\nwithout `OPENFIGI_API_KEY` holding resolution runs in anonymous mode.\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `get_company_facts(ticker)` | Normalized fundamentals (revenue, EPS, margins, debt) |\n| `get_financial_statement(ticker, statement, period)` | Income/balance/cashflow as structured JSON |\n| `get_filings(ticker, form_type, limit)` | Recent SEC filings (10-K/10-Q/8-K) with metadata and document URLs |\n| `parse_filing_section(url, section)` | Extract a 10-K section (Risk Factors, MD&A) as clean text |\n| `get_insider_trades(ticker, limit)` | Form 3/4/5 insider transactions (who, role, buy/sell, volume) |\n| `get_macro_series(series_id, start, end)` | FRED macro series (rates, inflation, unemployment) with metadata |\n| `get_quote(ticker)` | Real-time L1 quote (last/bid/ask/volume) via the Tradernet WebSocket feed |\n| `get_etf_holdings(ticker, limit)` | ETF/fund holdings (top by weight) + AUM, NAV, asset/country mix from SEC NPORT-P |\n| `get_holdings_analysis(symbol, limit)` | Look-through of an ETF/index: sector breakdown + weighted net-margin/ROE with coverage |\n| `get_index(index)` | Index snapshot (S&P 500, NASDAQ-100, Dow, NASDAQ Composite): level from FRED, tracking ETF, holdings preview |\n\n## Configuration\n\n| Variable | Description | Default |\n|---|---|---|\n| `EDGAR_USER_AGENT` | User-Agent for SEC requests | `EdgarMCP/0.1 (contact: info+sec@birthday.tools)` |\n| `EDGAR_RATE_LIMIT` | Requests per second | `10` |\n| `EDGAR_CACHE_DIR` | File cache directory | `edgar_cache` |\n| `FRED_API_KEY` | Free FRED key for `get_macro_series` / index levels | — |\n| `OPENFIGI_API_KEY` | Optional OpenFIGI key for higher CUSIP/ISIN rate limit | — |\n| `EDGAR_TELEMETRY` | Enable anonymous opt-in usage telemetry (`1`/`true`/`yes`/`on`) | off |\n| `EDGAR_TELEMETRY_URL` | Telemetry endpoint (only used when telemetry is enabled) | `https://t.birthday.tools/v1/events` |\n\nVariables are read from the environment; locally you can put them in a `.env` file.\n\n## Telemetry\n\nTelemetry is **opt-in and off by default**. Enable it by setting `EDGAR_TELEMETRY=1`.\nWhen enabled, the server periodically sends an anonymous, aggregated payload:\n\n- a random install id (generated once, stored locally),\n- the package version, Python minor version (e.g. `3.12`), and OS (`darwin`/`linux`/`windows`),\n- per-tool call counts and per-tool error counts.\n\nIt **never** sends request content — no tickers, arguments, results, error messages, IP\naddresses, file paths, or environment. Sending is fire-and-forget and never blocks or\nbreaks a tool call. Override the endpoint with `EDGAR_TELEMETRY_URL`, or leave telemetry\ndisabled (the default) to send nothing.\n\n## Architecture\n\nThree isolated layers: a platform-independent **data layer** (HTTP client with a host\nallowlist, ticker/name/CUSIP/ISIN resolution, XBRL normalizers, filing/ownership/NPORT-P\nparsers, FRED, the Tradernet WebSocket client, OpenFIGI identifier mapping, look-through\nand index analytics); a **cache layer** (aggressive caching of immutable filings and FIGI\nmappings; mutable FRED series are not cached); and a thin **MCP layer**. The data layer\nknows nothing about MCP and ports unchanged between a marketplace and self-hosting.\n\n## Security\n\n- Outbound requests are restricted to an HTTPS host allowlist (SSRF defense), centralized\n  across all sources (SEC, FRED, OpenFIGI).\n- Ownership and NPORT XML is parsed with `defusedxml` (XXE / billion-laughs defense).\n- Secrets (FRED / OpenFIGI keys) are redacted from error messages and never placed in URLs\n  or cache keys.\n- Real-time quotes come from Tradernet's public anonymous WebSocket feed\n  (`wss://wss.tradernet.com/`); a dedicated client with a hardcoded URL.\n- CUSIP/ISIN holding resolution goes through OpenFIGI (`api.openfigi.com`, allowlisted);\n  on failure it falls back to name matching.\n\n## Data licenses\n\nSEC EDGAR data is public domain, used with a descriptive `User-Agent` and the 10 req/s\nlimit. FRED data is provided by the Federal Reserve Bank of St. Louis under its\n[terms of use](https://fred.stlouisfed.org/legal/). Real-time quotes come from Tradernet's\npublic anonymous WebSocket feed. CUSIP/ISIN → ticker mapping uses\n[OpenFIGI](https://www.openfigi.com/) (Bloomberg; free tier, 25 req/min anonymous,\n250 req/min with a key).\n\n## License\n\n[MIT](LICENSE) © 2026 birthday.tools\n",
  "bytes": 5757,
  "sha": "d99fc1ea46ab9e39dc286774f361344937d57b2acc1c2f7451a81a993d6dacaf",
  "repo_slug": "birthday-tools/edgarmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_birthday_tools_edgarmcp_7bb9e5ed/readme"
}