io.github.danishashko/edgar-mcp

Official

by danishashko · Python

SEC EDGAR

SEC EDGAR filings (10-K, 10-Q, 8-K), XBRL financials, and full-text filing search. No API key.

SEC EDGAR filings, XBRL financial data, and full-text search for public company documents.

README.md7 KBView on GitHub

SEC EDGAR MCP Server 🏛️

U.S. SEC filings and financial data for Claude Desktop and any MCP-compatible client, powered by SEC EDGAR. Search companies, pull filings (10-K, 10-Q, 8-K, Form 4, ...), read XBRL financials, and full-text search across all filings — all from natural language. No API key required.

npm package: edgar-mcp · GitHub repo: danishashko/edgar-mcp.

🎯 What You Get

🔎 Company lookup by name or ticker → CIK
🗂️ Recent filings (any form type) with direct document links
📄 Latest filing of a type (newest 10-K / 10-Q / 8-K) in one call
💰 Financial highlights (revenue, net income, assets, equity, EPS) from XBRL
📈 Concept history — any GAAP line item over time
🔬 Full-text search across the last ~10 years of filings

Every tool returns human-readable markdown by default, or structured JSON on request (response_format: "json"). Lightweight (Python standard library + mcp only), no API key, retries on rate limits.

🚀 Quick Start

Add this to your Claude Desktop config and restart Claude:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "edgar": {
      "command": "npx",
      "args": ["-y", "edgar-mcp"],
      "env": {
        "SEC_USER_AGENT": "your-app-name your@email.com"
      }
    }
  }
}

The SEC asks every API client to send a descriptive User-Agent with contact info. Set SEC_USER_AGENT to your own name/email (a default is provided so it works out of the box). On first launch the npx wrapper creates an isolated Python environment and installs the dependency (one-time, ~a minute). You need Python 3.10+ and Node.js 16+.

Prefer a global install?

bash

npm install -g edgar-mcp

json

{
  "mcpServers": {
    "edgar": {
      "command": "edgar-mcp",
      "env": { "SEC_USER_AGENT": "your-app-name your@email.com" }
    }
  }
}

🔧 Available Tools

Tool	What it returns	Parameters
`search_company`	Companies matching a name/ticker, with their CIK	`query`, `limit`
`get_recent_filings`	Recent filings (form, dates, link), optional form filter	`identifier`, `form_type`, `limit`
`get_latest_filing`	The newest filing of a given type, with a document link	`identifier`, `form_type`
`get_company_facts`	Headline financials (revenue, net income, assets, equity, cash, EPS)	`identifier`
`get_concept`	One XBRL concept's reported history over time	`identifier`, `concept`, `limit`
`full_text_search`	Filings matching a keyword/phrase across all companies	`query`, `forms`, `limit`

Every tool also accepts response_format ("markdown", the default, or "json"). identifier accepts a ticker, CIK, or company name.

Common XBRL concepts for get_concept: Revenues / RevenueFromContractWithCustomerExcludingAssessedTax, NetIncomeLoss, Assets, Liabilities, StockholdersEquity, EarningsPerShareDiluted.

💬 Example Prompts

Once the server is connected, just ask Claude:

"What's Apple's latest 10-K?"
"Show me Tesla's recent 8-K filings."
"What are Microsoft's headline financials?"
"Show me NVIDIA's net income over the last few years."
"Which companies mention 'quantum computing' in their 10-Ks?"
"Find the CIK for Berkshire Hathaway."

🐛 Troubleshooting

"SEC EDGAR is rate-limiting requests" EDGAR allows ~10 requests/second. The server retries automatically; wait a moment if it persists.

"Not found" Use search_company to confirm the exact ticker/CIK first.

"Command not found" / "Python not found" Ensure Python 3.10+ and Node.js 16+ are installed and on your PATH. On macOS/Linux, try python3.

Tools not showing up in Claude

Confirm the config file is valid JSON (no trailing commas).
Fully quit and reopen Claude Desktop.

🛠️ Manual Installation (Alternative)

If you would rather run the Python file directly instead of via npx:

1. Download the server and install the dependency

bash

pip install mcp

(or pip3 on macOS/Linux)

2. Point Claude Desktop at it

json

{
  "mcpServers": {
    "edgar": {
      "command": "python3",
      "args": ["/absolute/path/to/edgar_mcp.py"],
      "env": { "SEC_USER_AGENT": "your-app-name your@email.com" }
    }
  }
}

On Windows use "command": "python" and a path like "C:\\path\\to\\edgar_mcp.py".

3. Restart Claude Desktop.

🔒 Privacy & Rate Limits

Uses the official SEC EDGAR APIs — public, no key.
Requests go straight from your machine to the SEC. Nothing is stored or proxied.
The SEC requires a descriptive User-Agent with contact info and limits ~10 requests/second.
Intended for personal, educational, and research use.

📝 Notes

identifier is flexible: ticker (AAPL), CIK (320193), or name (Apple).
Financial data comes from XBRL, first required by the SEC in 2009, so history goes back that far for most filers.
get_company_facts returns highlights; use get_concept for the full series of any one metric.

📋 Changelog

See CHANGELOG.md for the full version history.

📚 Resources

⚖️ Legal Disclaimer

This tool uses the public SEC EDGAR APIs but is not affiliated with or endorsed by the U.S. Securities and Exchange Commission. Use is subject to the SEC's website policies. Data is provided as-is for personal, educational, and research purposes; verify against the original filings before relying on it.

👤 Author

Daniel Shashko

GitHub: @danishashko
LinkedIn: daniel-shashko
npm: danielshashko

📄 License

Install

Configuration

Environment variables

SEC_USER_AGENT

Descriptive User-Agent with contact info required by the SEC, e.g. 'your-app your@email.com'

claude_desktop_config.json

{
  "mcpServers": {
    "edgar-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "edgar-mcp@1.0.2"
      ],
      "env": {
        "SEC_USER_AGENT": "<YOUR_SEC_USER_AGENT>"
      }
    }
  }
}