SEC EDGAR MCP Server
[CI] [PyPI] [MCP Registry]
A read-only Model Context Protocol server, over stdio, that
takes a stock ticker, resolves it to the SEC's Central Index Key (CIK), and returns filing
metadata with official EDGAR links. It exposes three tools, five resources and three prompts.
No API key is needed: SEC EDGAR is public, and the server only identifies itself with a
descriptive User-Agent. The server never reads, downloads or summarises filing contents; it
tells you which filings exist and where they are on sec.gov.
Published on PyPI as mcp-server-edgar and listed
on the Official MCP Registry
as io.github.SudiptoHaldar/mcp-server-edgar.
Install and run
The server is a Python package with a console entry point. The simplest way to run it is with
uv, which fetches Python 3.11 or newer when needed:
Or install it into any environment with Python 3.11 or newer:
The executable speaks MCP on stdin and stdout and is meant to be launched by an MCP client, so
on its own it waits for a client. To try it interactively, use the
MCP Inspector:
Configure your MCP client
Claude Desktop and most other JSON-configured clients take an mcpServers entry. The optional
env block sets the SEC fair-access contact (see Configuration):
Claude Code:
Tools
All three tools are read-only and return a JSON object whose status field says what happened
(see Results and errors). Years always refer to the filing date, the day the SEC received a
filing, never to the period the filing covers.
get_latest_filing — Latest SEC filing
Newest filing for a ticker, optionally restricted to given form types.
Example call get_latest_filing("AAPL", ["10-K"]); result abridged, values as of 2026-11-01:
filing is null when the company has no filing of the requested forms.
list_filings_by_year — Filings by year
Every filing a company submitted during one calendar year, newest first, in pages.
The year is the filing year, not the fiscal year: Apple's 10-K for the fiscal year ending
September 2025 was filed on 2025-10-31, so it belongs to year=2025; a 10-K filed in January
2026 for a fiscal year 2025 belongs to year=2026. Older years are served from the SEC's
history files automatically.
Example call list_filings_by_year("AAPL", 2025, ["10-K", "10-Q"]); result abridged, values as
of 2026-11-01:
To page, call again with offset set to next_offset until it is null. Pages never overlap.
A year with no filings is ok with total_count 0.
list_form_types — EDGAR form types
The EDGAR submission-type codes filed in recent quarters, most common first. Use it to learn
which values forms accepts: form is exactly the code EDGAR uses (10-K, 10-K/A,
SCHEDULE 13G/A, 424B2, NPORT-P).
The catalogue is a snapshot bundled with the package, counted over the four completed
quarters before the release and refreshed with each release; catalogue.generated_on and
catalogue.quarters say which. Calling it makes no request to the SEC. description and
topics come from the SEC Forms List when the form number is known, otherwise null.
Example call list_form_types("10-K"); result abridged, values as of 2026-11-01:
Results and errors
Every tool answers with a JSON object. Anticipated conditions are reported in status, never as
a protocol error, so a client can act on them:
Every object also carries a one-line message. A filing record always has form,
filing_date, report_date (the period covered, context only, may be null),
accession_number and filing_url (the official filing index page on sec.gov);
primary_document_url points at the main document when the SEC lists one and the file name is
safe, otherwise it is null.
Resources
Clients that can attach resources as context may read these JSON documents directly, without a
tool call. They are built by the same code path as the tools, so a resource and its tool always
agree.
Use the edgar://issuers/{cik}/… routes when a ticker is ambiguous; the CIK must be listed in
the SEC ticker map. Resources have no status envelope: an unknown ticker, a malformed or
unlisted CIK or an unmatched URI is a resource-not-found error, and an ambiguous ticker or an
SEC outage is a resource error, each carrying the same message text the tools use.
Prompts
Prompts are reusable instructions a person selects from the client's prompt menu; the client
inserts the rendered text and the model then uses the tools. They carry no live data.
Every prompt ends with the same guardrails: metadata and official sec.gov links only, the server
does not read filing contents, cite the EDGAR link for every filing, give no investment advice,
and on an ambiguous answer ask which issuer is meant before calling again with that cik.
Configuration
All settings are environment variables with defaults. Unset or empty values take the default; a
bad value stops startup with exit code 1 and one line on stderr naming the variable.
The SEC asks every automated client to identify itself with a contact address, so set
MCP_EDGAR_USER_AGENT to your own product name and e-mail. Logs go to stderr only; stdout
carries the protocol.
How it uses SEC EDGAR
- Ticker to CIK:
https://www.sec.gov/files/company_tickers_exchange.json, cached for a
day. One ticker listed under several CIKs is reported as ambiguous; one CIK with several
tickers (GOOGL, GOOG) is one issuer.
- Filings:
https://data.sec.gov/submissions/CIK##########.json (CIK zero-padded to ten
digits), cached for an hour. Older years are read from the history files the submissions
document lists, and only those whose date range overlaps the requested year.
- Links: the filing index page
…/Archives/edgar/data/<cik>/<accession>/<accession>-index.htm
is always returned; the primary document link is built from the SEC's file name after
rejecting anything that is not a plain file name.
- Fair access: at most 10 requests per second, a descriptive
User-Agent, in-memory
caching per process, and bounded retries with backoff on HTTP 429 and transient 5xx responses.
When the SEC still does not answer, the tool returns upstream_error with a retry hint rather
than an empty result. See the SEC's
EDGAR API documentation.
Known limits
- Metadata and links only: no filing contents, no XBRL financial facts, no summaries, no
investment advice.
year means the calendar year the SEC received the filing, not the fiscal year it reports on.- Years before 1993 (the start of electronic filing) are rejected as
invalid_input.
- Only issuers in the SEC ticker map can be looked up; funds and private filers without a
listed ticker are out of scope, and the server never queries an arbitrary CIK.
- The form-type catalogue is a snapshot taken before each release, not a live list.
- Transport is stdio only; there is no HTTP endpoint and no authentication.
- Caches live in memory for the lifetime of one server process.
- This project is not affiliated with or endorsed by the U.S. Securities and Exchange Commission.
Development
Before a release, refresh the bundled form-type catalogue, then build:
Releases are published by the tag-triggered workflow in .github/workflows/release.yml: a
vX.Y.Z tag on this repository builds, publishes to PyPI (Trusted Publishing, with attestations)
and to the MCP Registry, and verifies both.
Issues and pull requests: https://github.com/SudiptoHaldar/mcp_server_edgar/issues.
License
MIT, see LICENSE. SEC
EDGAR data is public domain and is served here under the SEC's fair-access rules.
