io.github.cyanheads/secedgar-mcp-server

Official16 toolsLive

by cyanheads · TypeScript

Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.

@cyanheads/secedgar-mcp-server

This Model Context Protocol (MCP) server enables querying SEC EDGAR filings, XBRL financials, and company data through MCP. It supports both STDIO and Streamable HTTP. The package is published as io.github.cyanheads/secedgar-mcp-server and includes 16 tools (+1 opt-in), plus resources and a prompt.

🛠️ Key Features

Query SEC EDGAR filings via MCP
Retrieve XBRL financials and company data
Accessible over STDIO and Streamable HTTP
16 tools (+1 opt-in)

🚀 Use Cases

Access SEC EDGAR data for developer workflows
Fetch XBRL financial information and associated company data
Integrate SEC-focused data retrieval into MCP-based systems

⚡ Developer Benefits

Uses Model Context Protocol interfaces for structured queries
Supports two transport options: STDIO and Streamable HTTP
Tooling breadth: 16 tools (+1 opt-in)

⚠️ Limitations

Specific tool names, output formats, and auth/streaming details are not provided in the available source excerpt.

Topics

edgarfinancial-datamcpmcp-servermodel-context-protocolsecsec-edgartypescriptxbrlfilingscyanheads

Captured live from the server via tools/list.

secedgar_company_search

Find companies and retrieve entity info with optional recent filings. Entry point for most EDGAR workflows — resolves tickers, names, or CIKs to entity details, with accession numbers in the result feeding secedgar_get_filing for document content. When a date or form filter carries the scan past the recent submissions window, the full filtered filing history is also staged as df_<id> — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Parameters6

query	string	required	Company ticker symbol (e.g., "AAPL", "VOO"), name (e.g., "Apple"), or CIK number (e.g., "320193"). Ticker is the fastest lookup and works for equities, ETFs, and mutual funds; a multi-class share ticker resolves in either form ("BRK-B" or "BRK.B"). Name search matches current and former names, and the corporate suffix does not have to match the registry's form ("Beacon Financial Corporation" finds "Beacon Financial Corp") — but Corp, Inc, Co, and Ltd stay distinct from each other, since separate registrants differ only by which one they use.
include_filings	boolean	optional	Include recent filings in the response. Set to false for entity-info-only lookups.
form_types	array	optional	Filter filings to specific form types (e.g., ["10-K", "10-Q", "8-K"]). Without this, returns all form types.
filing_limit	integer	optional	Maximum number of filings to return in the inline list.
filed_after	any	optional	Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches filings that predate the ~1000-filing recent window (e.g. a company's 2005 10-K).
filed_before	any	optional	Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Company ticker symbol (e.g., \"AAPL\", \"VOO\"), name (e.g., \"Apple\"), or CIK number (e.g., \"320193\"). Ticker is the fastest lookup and works for equities, ETFs, and mutual funds; a multi-class share ticker resolves in either form (\"BRK-B\" or \"BRK.B\"). Name search matches current and former names, and the corporate suffix does not have to match the registry's form (\"Beacon Financial Corporation\" finds \"Beacon Financial Corp\") — but Corp, Inc, Co, and Ltd stay distinct from each other, since separate registrants differ only by which one they use."
    },
    "include_filings": {
      "default": true,
      "description": "Include recent filings in the response. Set to false for entity-info-only lookups.",
      "type": "boolean"
    },
    "form_types": {
      "description": "Filter filings to specific form types (e.g., [\"10-K\", \"10-Q\", \"8-K\"]). Without this, returns all form types.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "filing_limit": {
      "default": 10,
      "description": "Maximum number of filings to return in the inline list.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "filed_after": {
      "description": "Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches filings that predate the ~1000-filing recent window (e.g. a company's 2005 10-K).",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "YYYY-MM-DD"
        }
      ]
    },
    "filed_before": {
      "description": "Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "YYYY-MM-DD"
        }
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_search_filings

Search EDGAR filings since 1993. Full-text search covers 2001-present (the EFTS index floor); pre-2001 date ranges (to 1993) are served from the archives by form and entity/date. Pre-2001 free text needs entity scope (ticker:/cik:) — with it, the tool reads the entity's matching filings and matches the terms locally, which costs a few seconds (SEC's request rate caps the scan at roughly 5s for the 50-document maximum). A range crossing 2001-01-01 is split at the boundary and the two eras merged, each row tagged with its source. Supports exact phrases, boolean operators, wildcards, and entity targeting (ticker:AAPL or cik:320193 in query). When the match set outruns the inline list it is also staged as df_<id> — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Parameters7

query	any	optional	Full-text search query. Optional — omit (or pass "") to browse by form type and/or entity instead, e.g. every S-1 in a date window, or a company's filings via ticker:/cik:. A date range alone is not a valid search; pair it with forms or entity targeting. The EFTS index that serves free text starts at 2001-01-01; a date range reaching earlier needs ticker:/cik: entity scope, which lets the tool read that entity's filings and match the terms locally (bounded to 50 documents, a few seconds at SEC's request rate), or drop the text terms to browse by form and date. When present, supports exact phrases ("material weakness"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), and entity targeting (ticker:AAPL or cik:320193 in the query); terms are AND'd by default. A multi-class share ticker resolves in either form — ticker:BRK-B and ticker:BRK.B scope to the same issuer. The pre-2001 local scan honors the same phrase / OR / exclusion / wildcard syntax.
forms	array	optional	Filter to specific form types (e.g., ["10-K", "10-Q", "8-K"]). Without this, searches all form types. Note: "10-K" also matches amendments filed as 10-K/A. SEC renamed the blockholder schedules on 2024-12-18 — filings before that date are "SC 13D"/"SC 13G", filings after are "SCHEDULE 13D"/"SCHEDULE 13G" — so a filter spanning that boundary must list both spellings. Ownership forms (3, 4, 5) are indexed by the reporting person (e.g., "LEVINSON ARTHUR D"), not the issuer — rows carry no transaction code, share count, or price. Use secedgar_get_insider_transactions to retrieve parsed ownership XML with person, relationship, transaction code, shares, and price.
start_date	any	optional	Start of date range (YYYY-MM-DD). Both start_date and end_date must be provided for date filtering.
end_date	any	optional	End of date range (YYYY-MM-DD). Both start_date and end_date must be provided for date filtering.
limit	integer	optional	Results per page. Max 100.
offset	integer	optional	Pagination offset. For sort=relevance on a 2001-onward search, EDGAR pages server-side up to its 10,000-result cap. Everywhere else the offset indexes the rows this call assembled and sorted: a single 100-row window for date sorts and entity targeting, the full matched set on a pre-2001 archive path, or both together on a range that crosses 2001-01-01. Offsets at or past those rows return nothing even when total is larger — switch to sort=relevance for deep pagination on a 2001-onward search, narrow the search (forms, dates, entity targeting), or query the dataframe. On a crossing range the two sides are assembled unevenly — the archive side contributes every row it matched, the full-text side one window of its total — so once the window runs out the rows jump to the pre-2001 era with the remaining full-text matches absent from the middle; search the 2001-onward era on its own to page through those.
sort	string	optional	Result ordering. "filing_date_desc" (default) returns most recent first. "filing_date_asc" returns oldest first. "relevance" returns SEC's native search-score order, which weights term match strength over recency. Date sorts re-order the top 100 hits returned by the search index — for broad queries with more than 100 matches and no entity targeting, date-newest filings may sit outside that window. Entity targeting (ticker:/cik:) or a narrower query keeps matches inside the window when absolute recency matters. On the no-query browse path (forms/entity only), EFTS has no relevance signal — every hit scores null — and returns filings in natural date-descending order, so all sort modes effectively yield newest-first. Pre-2001 archive results carry no relevance score either, so relevance collapses to date-descending there.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Full-text search query. Optional — omit (or pass \"\") to browse by form type and/or entity instead, e.g. every S-1 in a date window, or a company's filings via ticker:/cik:. A date range alone is not a valid search; pair it with forms or entity targeting. The EFTS index that serves free text starts at 2001-01-01; a date range reaching earlier needs ticker:/cik: entity scope, which lets the tool read that entity's filings and match the terms locally (bounded to 50 documents, a few seconds at SEC's request rate), or drop the text terms to browse by form and date. When present, supports exact phrases (\"material weakness\"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), and entity targeting (ticker:AAPL or cik:320193 in the query); terms are AND'd by default. A multi-class share ticker resolves in either form — ticker:BRK-B and ticker:BRK.B scope to the same issuer. The pre-2001 local scan honors the same phrase / OR / exclusion / wildcard syntax.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "minLength": 1,
          "description": "Full-text search query. Supports: exact phrases (\"material weakness\"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), entity targeting (ticker:AAPL or cik:320193 in the query). Terms are AND'd by default."
        }
      ]
    },
    "forms": {
      "description": "Filter to specific form types (e.g., [\"10-K\", \"10-Q\", \"8-K\"]). Without this, searches all form types. Note: \"10-K\" also matches amendments filed as 10-K/A. SEC renamed the blockholder schedules on 2024-12-18 — filings before that date are \"SC 13D\"/\"SC 13G\", filings after are \"SCHEDULE 13D\"/\"SCHEDULE 13G\" — so a filter spanning that boundary must list both spellings. Ownership forms (3, 4, 5) are indexed by the reporting person (e.g., \"LEVINSON ARTHUR D\"), not the issuer — rows carry no transaction code, share count, or price. Use secedgar_get_insider_transactions to retrieve parsed ownership XML with person, relationship, transaction code, shares, and price.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start_date": {
      "description": "Start of date range (YYYY-MM-DD). Both start_date and end_date must be provided for date filtering.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "YYYY-MM-DD"
        }
      ]
    },
    "end_date": {
      "description": "End of date range (YYYY-MM-DD). Both start_date and end_date must be provided for date filtering.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "YYYY-MM-DD"
        }
      ]
    },
    "limit": {
      "default": 20,
      "description": "Results per page. Max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset. For sort=relevance on a 2001-onward search, EDGAR pages server-side up to its 10,000-result cap. Everywhere else the offset indexes the rows this call assembled and sorted: a single 100-row window for date sorts and entity targeting, the full matched set on a pre-2001 archive path, or both together on a range that crosses 2001-01-01. Offsets at or past those rows return nothing even when total is larger — switch to sort=relevance for deep pagination on a 2001-onward search, narrow the search (forms, dates, entity targeting), or query the dataframe. On a crossing range the two sides are assembled unevenly — the archive side contributes every row it matched, the full-text side one window of its total — so once the window runs out the rows jump to the pre-2001 era with the remaining full-text matches absent from the middle; search the 2001-onward era on its own to page through those.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9999
    },
    "sort": {
      "default": "filing_date_desc",
      "description": "Result ordering. \"filing_date_desc\" (default) returns most recent first. \"filing_date_asc\" returns oldest first. \"relevance\" returns SEC's native search-score order, which weights term match strength over recency. Date sorts re-order the top 100 hits returned by the search index — for broad queries with more than 100 matches and no entity targeting, date-newest filings may sit outside that window. Entity targeting (ticker:/cik:) or a narrower query keeps matches inside the window when absolute recency matters. On the no-query browse path (forms/entity only), EFTS has no relevance signal — every hit scores null — and returns filings in natural date-descending order, so all sort modes effectively yield newest-first. Pre-2001 archive results carry no relevance score either, so relevance collapses to date-descending there.",
      "type": "string",
      "enum": [
        "filing_date_desc",
        "filing_date_asc",
        "relevance"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_filing

Fetch a specific filing's metadata and document content by accession number. Returns the primary document as readable text. Use offset/next_offset for multi-page access to large filings (10-K, S-1 can exceed 1M chars): pass the next_offset from a truncated response to read the next page. Use section to jump directly to a heading (e.g. 'risk factors', 'item 7') without needing an offset.

Parameters7

accession_number	string	required	Filing accession number in either format: "0000320193-23-000106" (dashes) or "000032019323000106" (no dashes). Obtained from secedgar_company_search or secedgar_search_filings results.
cik	string	optional	Company CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, likely filing CIKs are inferred from SEC search metadata and archive paths.
content_limit	integer	optional	Maximum characters of document text to return per page. 10-K filings can exceed 500,000 characters; S-1/A can exceed 1,000,000. Default 50,000 captures ~12,000 words (typically business overview, risk factors, and MD&A). Increase to 200,000 for full financial statements, or decrease for quick summaries. Use offset or section for subsequent pages.
document	string	optional	Specific document filename within the filing (e.g., "ex-21.htm" for subsidiaries list). Default: the primary document. Available documents are listed in the response metadata under documents; entries marked binary hold no text and are rejected.
include_xbrl	boolean	optional	Include XBRL viewer artifacts and machine-readable taxonomy files (R.htm fragments, _cal/_def/_lab/_pre.xml linkbases, _htm.xml inline instance, .xsd schemas, MetaLinks.json, FilingSummary.xml, Show.js, report.css, -xbrl.zip, Financial_Report.xlsx, EX-101. technical exhibits) under documents.xbrl. Off by default — these dominate filing indexes (~100 entries on a typical 10-K) and are rarely relevant when reading filing content.
offset	integer	optional	Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page. Default 0 reads from the beginning.
section	string	optional	Jump to a named section by case-insensitive substring match against detected headings (e.g. 'risk factors', 'item 7', 'certain relationships'). Matching also ignores whitespace and quote-style differences, so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones. Takes precedence over offset when both are provided. On a miss, the error message includes the detected outline so you can pick the correct heading.

Raw schema

{
  "type": "object",
  "properties": {
    "accession_number": {
      "type": "string",
      "pattern": "^(?:\\d{10}-\\d{2}-\\d{6}|\\d{18})$",
      "description": "Filing accession number in either format: \"0000320193-23-000106\" (dashes) or \"000032019323000106\" (no dashes). Obtained from secedgar_company_search or secedgar_search_filings results."
    },
    "cik": {
      "description": "Company CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, likely filing CIKs are inferred from SEC search metadata and archive paths.",
      "type": "string",
      "pattern": "^\\d{1,10}$"
    },
    "content_limit": {
      "default": 50000,
      "description": "Maximum characters of document text to return per page. 10-K filings can exceed 500,000 characters; S-1/A can exceed 1,000,000. Default 50,000 captures ~12,000 words (typically business overview, risk factors, and MD&A). Increase to 200,000 for full financial statements, or decrease for quick summaries. Use offset or section for subsequent pages.",
      "type": "integer",
      "minimum": 1000,
      "maximum": 200000
    },
    "document": {
      "description": "Specific document filename within the filing (e.g., \"ex-21.htm\" for subsidiaries list). Default: the primary document. Available documents are listed in the response metadata under documents; entries marked binary hold no text and are rejected.",
      "type": "string"
    },
    "include_xbrl": {
      "default": false,
      "description": "Include XBRL viewer artifacts and machine-readable taxonomy files (R*.htm fragments, *_cal/_def/_lab/_pre.xml linkbases, *_htm.xml inline instance, *.xsd schemas, MetaLinks.json, FilingSummary.xml, Show.js, report.css, *-xbrl.zip, Financial_Report.xlsx, EX-101.* technical exhibits) under documents.xbrl. Off by default — these dominate filing indexes (~100 entries on a typical 10-K) and are rarely relevant when reading filing content.",
      "type": "boolean"
    },
    "offset": {
      "default": 0,
      "description": "Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page. Default 0 reads from the beginning.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "section": {
      "description": "Jump to a named section by case-insensitive substring match against detected headings (e.g. 'risk factors', 'item 7', 'certain relationships'). Matching also ignores whitespace and quote-style differences, so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones. Takes precedence over offset when both are provided. On a miss, the error message includes the detected outline so you can pick the correct heading.",
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "accession_number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_financials

Get historical XBRL financial data for a company. Accepts friendly concept names (e.g., "revenue", "net_income", "assets") or raw XBRL tags. Discover available friendly names with secedgar_search_concepts. Handles historical tag changes and deduplicates data automatically. The full series is also staged as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Parameters5

company	string	required	Ticker symbol (e.g., "AAPL") or CIK number. Ticker is preferred.
concept	string	required	Financial concept — friendly name (e.g., "revenue", "net_income", "assets", "eps_diluted") or raw XBRL tag (e.g., "AccountsPayableCurrent"). Friendly names auto-resolve to the correct XBRL tags and handle historical tag changes.
taxonomy	string	optional	XBRL taxonomy. us-gaap for US companies, ifrs-full for foreign filers, dei for entity info (shares outstanding).
period_type	string	optional	Filter to annual (FY) or quarterly (Q1-Q4) data. "all" returns both. When omitted, defaults to "annual"; instant (balance-sheet) concepts automatically fall back to returning the full series on the first call when the annual filter yields nothing (#48).
limit	integer	optional	Cap the inline data[] to the most-recent N periods (the series is newest-first). The full series is always registered to the dataframe, so older periods stay queryable via secedgar_dataframe_query. Omit to return every period inline.

Raw schema

{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "minLength": 1,
      "description": "Ticker symbol (e.g., \"AAPL\") or CIK number. Ticker is preferred."
    },
    "concept": {
      "type": "string",
      "minLength": 1,
      "description": "Financial concept — friendly name (e.g., \"revenue\", \"net_income\", \"assets\", \"eps_diluted\") or raw XBRL tag (e.g., \"AccountsPayableCurrent\"). Friendly names auto-resolve to the correct XBRL tags and handle historical tag changes."
    },
    "taxonomy": {
      "default": "us-gaap",
      "description": "XBRL taxonomy. us-gaap for US companies, ifrs-full for foreign filers, dei for entity info (shares outstanding).",
      "type": "string",
      "enum": [
        "us-gaap",
        "ifrs-full",
        "dei"
      ]
    },
    "period_type": {
      "description": "Filter to annual (FY) or quarterly (Q1-Q4) data. \"all\" returns both. When omitted, defaults to \"annual\"; instant (balance-sheet) concepts automatically fall back to returning the full series on the first call when the annual filter yields nothing (#48).",
      "type": "string",
      "enum": [
        "annual",
        "quarterly",
        "all"
      ]
    },
    "limit": {
      "description": "Cap the inline data[] to the most-recent N periods (the series is newest-first). The full series is always registered to the dataframe, so older periods stay queryable via secedgar_dataframe_query. Omit to return every period inline.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "company",
    "concept"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_snapshot

Build a company financial profile in one call: the latest value of every supported XBRL concept, grouped by statement. Reads the filer's complete companyfacts payload once rather than one request per concept, so it replaces a run of secedgar_get_financials calls when the question is "what do this company's financials look like right now". Values use the same frame dedup and tag priority as secedgar_get_financials, so the two agree for any concept they both cover. Duration concepts (income statement, cash flow, per-share) report their latest full year and latest single quarter; balance-sheet and entity-info concepts report their latest point-in-time value, since that is the only form they are filed in. A concept the filer does not report is listed under gaps with the XBRL tags that were tried — never zero-filled or interpolated. Use secedgar_get_financials for a full time series of one concept, and secedgar_compare_companies to put several companies side by side.

Parameters3

company	string	required	Ticker symbol (e.g. "AAPL") or CIK number. Ticker is preferred.
taxonomy	string	optional	XBRL taxonomy to resolve concepts under. Every concept is looked up in this one taxonomy, so ifrs-full covers only the concepts with confirmed IFRS tag variants and the rest — including the dei entity-info concepts — come back under gaps. Leave at us-gaap for domestic filers, where each concept uses its own preferred taxonomy.
period_type	string	optional	Which duration periods to report per concept: the latest full year, the latest single quarter, or both (default). Balance-sheet and entity-info concepts are point-in-time and always report their latest instant value regardless of this setting.

Raw schema

{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "minLength": 1,
      "description": "Ticker symbol (e.g. \"AAPL\") or CIK number. Ticker is preferred."
    },
    "taxonomy": {
      "default": "us-gaap",
      "description": "XBRL taxonomy to resolve concepts under. Every concept is looked up in this one taxonomy, so ifrs-full covers only the concepts with confirmed IFRS tag variants and the rest — including the dei entity-info concepts — come back under gaps. Leave at us-gaap for domestic filers, where each concept uses its own preferred taxonomy.",
      "type": "string",
      "enum": [
        "us-gaap",
        "ifrs-full"
      ]
    },
    "period_type": {
      "default": "both",
      "description": "Which duration periods to report per concept: the latest full year, the latest single quarter, or both (default). Balance-sheet and entity-info concepts are point-in-time and always report their latest instant value regardless of this setting.",
      "type": "string",
      "enum": [
        "annual",
        "quarterly",
        "both"
      ]
    }
  },
  "required": [
    "company"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_material_events

Retrieve a company's 8-K filings with their item codes decoded, optionally filtered to specific items. 8-K item codes are how material events are actually scoped — 1.01 material agreements, 2.02 results of operations, 4.02 non-reliance on previously issued financials, 5.02 officer and director departures — and filtering by them is narrower than any form-level filter in secedgar_search_filings or secedgar_company_search, neither of which can see items. Each row carries the accession number and primary document for secedgar_get_filing; press releases usually ride as EX-99 exhibits rather than in the primary document. Two numbering regimes exist: filings from 2004-08-23 onward use the x.xx codes, earlier ones use single integers (12 was the old results-of-operations item, 9 the old Regulation FD item), and both are accepted as filters and decoded in the response. A date window reaches filings older than the recent submissions window by paging into the archive. The full filtered set is materialized as df_<id> for item-distribution analysis over time — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Parameters5

company	string	required	Company ticker symbol (e.g. "AAPL"), name (e.g. "Apple"), or CIK number (e.g. "320193"). Ticker is the exact lookup; name search matches current and former names.
items	array	optional	Item codes to filter to; a filing matches when it reports any of them. Omit to return every 8-K. Current-regime codes are dotted ("2.02"), pre-2004-08-23 codes are bare integers ("12"), and the two vocabularies do not overlap — filtering on "2.02" alone returns nothing from a pre-2004 window, so pair them ("2.02", "12") when the window spans the changeover. Full decode table: the secedgar://filing-types resource.
filed_after	any	optional	Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches 8-K filings that predate the ~1000-filing recent window.
filed_before	any	optional	Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan.
limit	integer	optional	Filings returned inline, newest first. The full filtered set is materialized as a dataframe when it exceeds this and a canvas is available. Default 20.

Raw schema

{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "minLength": 1,
      "description": "Company ticker symbol (e.g. \"AAPL\"), name (e.g. \"Apple\"), or CIK number (e.g. \"320193\"). Ticker is the exact lookup; name search matches current and former names."
    },
    "items": {
      "description": "Item codes to filter to; a filing matches when it reports any of them. Omit to return every 8-K. Current-regime codes are dotted (\"2.02\"), pre-2004-08-23 codes are bare integers (\"12\"), and the two vocabularies do not overlap — filtering on \"2.02\" alone returns nothing from a pre-2004 window, so pair them (\"2.02\", \"12\") when the window spans the changeover. Full decode table: the secedgar://filing-types resource.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "1",
          "2",
          "3",
          "4",
          "5",
          "6",
          "7",
          "8",
          "9",
          "10",
          "11",
          "12",
          "1.01",
          "1.02",
          "1.03",
          "1.04",
          "1.05",
          "2.01",
          "2.02",
          "2.03",
          "2.04",
          "2.05",
          "2.06",
          "3.01",
          "3.02",
          "3.03",
          "4.01",
          "4.02",
          "5.01",
          "5.02",
          "5.03",
          "5.04",
          "5.05",
          "5.06",
          "5.07",
          "5.08",
          "6.01",
          "6.02",
          "6.03",
          "6.04",
          "6.05",
          "6.06",
          "7.01",
          "8.01",
          "9.01"
        ]
      }
    },
    "filed_after": {
      "description": "Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches 8-K filings that predate the ~1000-filing recent window.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "YYYY-MM-DD"
        }
      ]
    },
    "filed_before": {
      "description": "Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "description": "YYYY-MM-DD"
        }
      ]
    },
    "limit": {
      "default": 20,
      "description": "Filings returned inline, newest first. The full filtered set is materialized as a dataframe when it exceeds this and a canvas is available. Default 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "company"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_insider_transactions

Fetch Form 4 insider transactions (purchases, sales, grants, exercises) for a company by parsing SEC EDGAR ownership XML. Returns the reporting person, their relationship to the issuer, transaction date, type, shares traded (absolute magnitude), direction (acquire/dispose), price per share, and shares owned after the transaction. Covers nonDerivative transactions (open-market buys/sells, gifts) and derivative transactions (option exercises, RSU vests). When a canvas is available, the full set of transactions parsed from the scanned recent filings is materialized as df_<id> (the inline list is a preview capped at limit) — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate net buy/sell by insider: SUM(CASE WHEN direction='dispose' THEN -shares_traded ELSE shares_traded END). Use secedgar_search_filings with forms=["4"] for broader date-range queries or to search across all companies.

Parameters3

ticker_or_cik	string	required	Company ticker symbol (e.g., "AAPL") or 10-digit CIK number (e.g., "0000320193"). The issuer, not the reporting person.
transaction_type	string	optional	Filter by direction. "purchase" = open-market buys (code P). "sale" = open-market sells (code S). "all" includes grants, awards, exercises, gifts, and other coded transaction types as well.
limit	integer	optional	Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20.

Raw schema

{
  "type": "object",
  "properties": {
    "ticker_or_cik": {
      "type": "string",
      "minLength": 1,
      "description": "Company ticker symbol (e.g., \"AAPL\") or 10-digit CIK number (e.g., \"0000320193\"). The issuer, not the reporting person."
    },
    "transaction_type": {
      "default": "all",
      "description": "Filter by direction. \"purchase\" = open-market buys (code P). \"sale\" = open-market sells (code S). \"all\" includes grants, awards, exercises, gifts, and other coded transaction types as well.",
      "type": "string",
      "enum": [
        "purchase",
        "sale",
        "all"
      ]
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "ticker_or_cik"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_institutional_holdings

Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML. ticker_or_cik is the institutional filer — its 10-digit CIK (e.g. 0000102909), or an entity name resolved through EDGAR entity search — and the tool returns what that institution holds. A name that matches several EDGAR filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK, rather than guessing. For the reverse direction — which institutions hold a given portfolio company — use secedgar_find_holders, whose filer_cik results feed straight back into this tool. The 13F information table lists each position: issuer name, CUSIP, shares held, market value (in whole USD), and put/call designation for options. Sub-lines for the same security are consolidated into distinct positions sorted by value by default (set consolidate=false for raw filing rows). The inline holdings list is one page of limit rows starting at offset — pass the returned next_offset to walk further down a large information table. The full parsed holdings set is also materialized as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate the whole filing or self-join across quarters on cusip + reporting_period. Institutions with less than $100M in 13(f) securities are exempt and may not file. Use secedgar_search_filings with forms=["13F-HR"] for broader search.

Parameters5

ticker_or_cik	string	required	The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. "0000102909" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like "AAPL" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction.
quarter	string	optional	Reporting quarter to target, in "YYYY-QN" format (e.g., "2025-Q4"). When omitted, returns the most recent 13F-HR available. Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026.
limit	integer	optional	Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20.
offset	integer	optional	Row to start the page at, 0-based, over the ordered position list. Pass the next_offset from the previous response to read the next page — the filing is parsed whole and sliced, so paging is stable and gap-free. An offset at or past the position count returns an empty page.
consolidate	boolean	optional	When true (default), info-table sub-lines for the same security (CUSIP + class + put/call) are summed into one position and results are sorted by market value descending, so `limit` returns the largest distinct holdings. Set false to return raw information-table rows in filing order (one per investment-discretion/manager sub-line), preserving investment_discretion.

Raw schema

{
  "type": "object",
  "properties": {
    "ticker_or_cik": {
      "type": "string",
      "minLength": 1,
      "description": "The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form) or an entity name. Names resolve through EDGAR entity search, which covers institutional managers absent from the ticker file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction."
    },
    "quarter": {
      "description": "Reporting quarter to target, in \"YYYY-QN\" format (e.g., \"2025-Q4\"). When omitted, returns the most recent 13F-HR available. Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "default": 0,
      "description": "Row to start the page at, 0-based, over the ordered position list. Pass the next_offset from the previous response to read the next page — the filing is parsed whole and sliced, so paging is stable and gap-free. An offset at or past the position count returns an empty page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "consolidate": {
      "default": true,
      "description": "When true (default), info-table sub-lines for the same security (CUSIP + class + put/call) are summed into one position and results are sorted by market value descending, so `limit` returns the largest distinct holdings. Set false to return raw information-table rows in filing order (one per investment-discretion/manager sub-line), preserving investment_discretion.",
      "type": "boolean"
    }
  },
  "required": [
    "ticker_or_cik"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_find_holders

Find which institutional managers reported holding an issuer, by searching 13F-HR information tables for one reporting quarter. This is the reverse direction of secedgar_get_institutional_holdings: that tool takes a manager and returns its portfolio, this one takes an issuer and returns its managers — pass a returned filer_cik plus the same quarter to read the actual position. Searching by cusip is the precise path, matching the identifier the information table itself carries; without it the issuer name is matched as a phrase against the filing text, which both over-matches (unrelated issuers sharing a word) and under-matches (managers writing the name differently), so prefer cusip whenever one is known. A CUSIP cannot be derived from a ticker here — read one off any 13F information table returned by secedgar_get_institutional_holdings. The returned list is unranked: the search index scores by text relevance, which carries no signal about position size, and no ordering by shares or market value is available without opening each filing. Managers holding under $100M in 13(f) securities are exempt from filing at all. When more managers match than fit inline, the full fetched set is staged as df_<id> — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Parameters4

issuer	string	required	The portfolio company whose holders you want — a ticker ("AAPL"), a 10-digit CIK ("0000320193"), or a company name. Without cusip, this resolves to the company's EDGAR-conformed name and that name is phrase-matched against 13F information tables, so it must identify one company. With cusip supplied, it is used only to label the result.
cusip	any	optional	The issuer's 9-character CUSIP (e.g. "037833100" for Apple common stock; foreign issuers use a CINS starting with a letter, e.g. "H1467J104"). The precise match key — information tables identify every position by CUSIP, so this avoids the name-phrase misses. Each share class has its own CUSIP, so a multi-class issuer needs one call per class. Read a CUSIP off the holdings returned by secedgar_get_institutional_holdings.
quarter	any	optional	Reporting quarter to search, "YYYY-QN" (e.g. "2026-Q1"). Omit for the newest quarter whose 45-day filing deadline has passed — the applied quarter and its filing window are echoed in the response. A quarter still inside its deadline returns nothing, because the filings do not exist yet.
limit	integer	optional	Filer rows returned inline. The full fetched set (up to 500 rows) is materialized as a dataframe when a canvas is available. Default 20.

Raw schema

{
  "type": "object",
  "properties": {
    "issuer": {
      "type": "string",
      "minLength": 1,
      "description": "The portfolio company whose holders you want — a ticker (\"AAPL\"), a 10-digit CIK (\"0000320193\"), or a company name. Without cusip, this resolves to the company's EDGAR-conformed name and that name is phrase-matched against 13F information tables, so it must identify one company. With cusip supplied, it is used only to label the result."
    },
    "cusip": {
      "description": "The issuer's 9-character CUSIP (e.g. \"037833100\" for Apple common stock; foreign issuers use a CINS starting with a letter, e.g. \"H1467J104\"). The precise match key — information tables identify every position by CUSIP, so this avoids the name-phrase misses. Each share class has its own CUSIP, so a multi-class issuer needs one call per class. Read a CUSIP off the holdings returned by secedgar_get_institutional_holdings.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^[0-9A-Za-z]{9}$",
          "description": "9-character CUSIP/CINS"
        }
      ]
    },
    "quarter": {
      "description": "Reporting quarter to search, \"YYYY-QN\" (e.g. \"2026-Q1\"). Omit for the newest quarter whose 45-day filing deadline has passed — the applied quarter and its filing window are echoed in the response. A quarter still inside its deadline returns nothing, because the filings do not exist yet.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{4}-Q[1-4]$",
          "description": "YYYY-QN"
        }
      ]
    },
    "limit": {
      "default": 20,
      "description": "Filer rows returned inline. The full fetched set (up to 500 rows) is materialized as a dataframe when a canvas is available. Default 20.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "issuer"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_beneficial_owners

List the 5%-and-over beneficial owners of a public company, parsed from the structured SCHEDULE 13D and SCHEDULE 13G filings made about it. The input is the ISSUER — the company being held — which is the opposite direction from secedgar_get_institutional_holdings, where the input is the manager. 13D is the activist form and carries the filer's stated purpose of the transaction; 13G is the passive form and has no purpose field at all, which is the substantive difference between a stake that intends to influence control and one that does not. Every filing is returned with each reporting person listed separately, because voting power, dispositive power, and percent of class are reported per person even on a joint filing where several funds and their controlling principal report overlapping shares — summing those percentages double-counts the same position. Coverage starts at 2024-12-18, when SEC replaced the legacy SC 13D / SC 13G text filings with this XML format; earlier stakes are readable but not parseable, and the response reports how many of them the issuer has. The full parsed set is materialized as df_<id> when a canvas is available, one row per reporting person, so it joins against the insider and 13F dataframes on issuer CIK — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.

Parameters4

issuer	string	required	The company whose blockholders you want — a ticker ("AAPL"), a 10-digit CIK ("0000320193"), or a company name. This is the subject company of the schedule, not the investor filing it; passing an investment manager here returns the schedules filed about that manager, which is almost always empty.
form_kind	string	optional	Which schedule to return. "13D" is the activist form, filed by a holder that may seek to influence control and carrying a stated purpose of transaction. "13G" is the passive form, available to institutions and holders under 20% that certify no control intent. "all" (default) returns both, newest first.
include_amendments	boolean	optional	Whether to include amendments (SCHEDULE 13D/A, SCHEDULE 13G/A). Amendments carry the current position and are how an ongoing stake is tracked, so they are included by default. Set false to see only filings that opened a new position.
limit	integer	optional	Number of filings to fetch and parse, newest first. Each filing is a separate document fetch, so this is the cost of the call as well as its depth. Default 10; a widely-held company can have dozens of blockholder filings a year.

Raw schema

{
  "type": "object",
  "properties": {
    "issuer": {
      "type": "string",
      "minLength": 1,
      "description": "The company whose blockholders you want — a ticker (\"AAPL\"), a 10-digit CIK (\"0000320193\"), or a company name. This is the subject company of the schedule, not the investor filing it; passing an investment manager here returns the schedules filed about that manager, which is almost always empty."
    },
    "form_kind": {
      "default": "all",
      "description": "Which schedule to return. \"13D\" is the activist form, filed by a holder that may seek to influence control and carrying a stated purpose of transaction. \"13G\" is the passive form, available to institutions and holders under 20% that certify no control intent. \"all\" (default) returns both, newest first.",
      "type": "string",
      "enum": [
        "all",
        "13D",
        "13G"
      ]
    },
    "include_amendments": {
      "default": true,
      "description": "Whether to include amendments (SCHEDULE 13D/A, SCHEDULE 13G/A). Amendments carry the current position and are how an ongoing stake is tracked, so they are included by default. Set false to see only filings that opened a new position.",
      "type": "boolean"
    },
    "limit": {
      "default": 10,
      "description": "Number of filings to fetch and parse, newest first. Each filing is a separate document fetch, so this is the cost of the call as well as its depth. Default 10; a widely-held company can have dozens of blockholder filings a year.",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "issuer"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_get_fund_holdings

List what an ETF or mutual fund holds, parsed from the NPORT-P portfolio report it files with the SEC every quarter. The input is the fund — a ticker like VOO, a fund series ID, or the registrant trust — which is the opposite direction from the ownership tools: secedgar_get_institutional_holdings and secedgar_find_holders answer who owns a company, this answers what a fund owns. Each position carries the security name, CUSIP/ISIN/LEI where the filer reports them, share balance, market value in USD, and percent of the fund's net assets, alongside fund-level net assets and total assets. Positions are returned largest-first by percent of net assets, one page of limit rows starting at offset; the full report registers as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query, which is how a fund running to thousands of positions is aggregated or joined against the 13F and insider dataframes. An NPORT-P covers exactly one fund series and a registrant trust files one report per series, so a trust with several funds needs the specific fund named — pass its ticker or series_id. Reports publish roughly two months after the period they cover, so every result is dated: the holdings are the portfolio as of report_period_date, not as of today.

Parameters5

fund	string	required	The fund whose portfolio you want — a fund ticker ("VOO", "SCHD"), an SEC fund series ID ("S000002839"), or a 10-digit CIK. A ticker names one share class of one series and routes directly; a CIK names the registrant, which files a separate report per series and needs series_id when it runs more than one fund. Fund trusts are indexed by ticker and series, not by name, so a trust name only resolves for a fund that trades under its own name ("SPDR S&P 500 ETF Trust") — pass the CIK otherwise.
series_id	string	optional	SEC fund series identifier ("S000002839"), naming which fund of the registrant to report. Takes precedence over any series the fund input implies. Series IDs come back on fund results from secedgar_company_search and in the series list of a series_required error.
report_date	string	optional	Target a specific reporting period by its last day (YYYY-MM-DD), e.g. "2025-12-31". Omit for the most recent report. Period ends follow the fund's own fiscal quarters, which are not always calendar quarters — Direxion funds report to February, May, August, and November. available_report_periods in the response lists the ones this call identified; a period missing from that list is still worth requesting directly, since a report the submissions window no longer dates is dated by reading it.
limit	integer	optional	Number of positions to return inline, largest first by percent of net assets. Default 20. A broad index fund reports thousands of positions, so the inline list is a preview — read the whole portfolio from the dataframe, or page it with offset.
offset	integer	optional	Position to start the page at, 0-based, over the full ordered holdings list. Pass the returned next_offset to read the next page — the report is parsed whole and sliced, so paging is stable and gap-free.

Raw schema

{
  "type": "object",
  "properties": {
    "fund": {
      "type": "string",
      "minLength": 1,
      "description": "The fund whose portfolio you want — a fund ticker (\"VOO\", \"SCHD\"), an SEC fund series ID (\"S000002839\"), or a 10-digit CIK. A ticker names one share class of one series and routes directly; a CIK names the registrant, which files a separate report per series and needs series_id when it runs more than one fund. Fund trusts are indexed by ticker and series, not by name, so a trust name only resolves for a fund that trades under its own name (\"SPDR S&P 500 ETF Trust\") — pass the CIK otherwise."
    },
    "series_id": {
      "description": "SEC fund series identifier (\"S000002839\"), naming which fund of the registrant to report. Takes precedence over any series the fund input implies. Series IDs come back on fund results from secedgar_company_search and in the series list of a series_required error.",
      "type": "string",
      "pattern": "^S\\d{9}$"
    },
    "report_date": {
      "description": "Target a specific reporting period by its last day (YYYY-MM-DD), e.g. \"2025-12-31\". Omit for the most recent report. Period ends follow the fund's own fiscal quarters, which are not always calendar quarters — Direxion funds report to February, May, August, and November. available_report_periods in the response lists the ones this call identified; a period missing from that list is still worth requesting directly, since a report the submissions window no longer dates is dated by reading it.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "limit": {
      "default": 20,
      "description": "Number of positions to return inline, largest first by percent of net assets. Default 20. A broad index fund reports thousands of positions, so the inline list is a preview — read the whole portfolio from the dataframe, or page it with offset.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Position to start the page at, 0-based, over the full ordered holdings list. Pass the returned next_offset to read the next page — the report is parsed whole and sliced, so paging is stable and gap-free.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "fund"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_fetch_frames

Fetch SEC XBRL frames for one concept × one period across all reporting companies. Inline response returns a page of the ranked companies — start at the top or pass offset/next_offset to walk further down the ranking; the full frames response (all reporters) is materialized as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query. Accepts friendly names like "revenue" or "assets" (discover via secedgar_search_concepts) or raw XBRL tags. One call hits one XBRL tag — when a friendly name maps to multiple same-meaning tags, the response's `unqueried_tags` lists the others; call again per tag and UNION/COALESCE in SQL with an analysis-specific priority (e.g. SalesRevenueGoodsNet is goods-only). The response's `related_tags` separately flags alternate-DEFINITION tags a meaningful share of filers use as their primary line (e.g. cash incl. restricted cash, equity incl. noncontrolling interest) — a whole-universe screen on the base tag silently omits those filers; query them separately, but do not blindly union (the semantics differ). Response includes `value_distribution` and `period_end_range` to flag XBRL scale-factor anomalies and fiscal-year mixing.

Parameters6

concept	string	required	Financial concept — same friendly names as secedgar_get_financials (e.g., "revenue", "assets", "eps_basic") or raw XBRL tag.
period	string	required	Calendar period. Use duration periods (no I suffix) for income/cash-flow items: "CY2023" (full year), "CY2024Q2" (single quarter). Use instant periods (I suffix) for balance-sheet items: "CY2023Q4I" (snapshot at Q4 close).
unit	string	optional	Unit of measure. Use "USD-per-shares" (or equivalently "USD/shares") for EPS, "shares" for share counts, "pure" for ratios. Ignored when concept resolves to a friendly name with a known unit.
limit	integer	optional	Number of companies to return.
offset	integer	optional	Rank to start the page at, 0-based, over the sorted frame. Pass the next_offset from the previous response to read the next page — the ranked list is fetched whole and sliced, so paging is stable and gap-free. An offset at or past total_companies returns an empty page.
sort	string	optional	Sort direction. "desc" for highest values first (typical for revenue, assets). "asc" for lowest values.

Raw schema

{
  "type": "object",
  "properties": {
    "concept": {
      "type": "string",
      "minLength": 1,
      "description": "Financial concept — same friendly names as secedgar_get_financials (e.g., \"revenue\", \"assets\", \"eps_basic\") or raw XBRL tag."
    },
    "period": {
      "type": "string",
      "minLength": 1,
      "pattern": "^CY\\d{4}(Q[1-4]I?)?$",
      "description": "Calendar period. Use duration periods (no I suffix) for income/cash-flow items: \"CY2023\" (full year), \"CY2024Q2\" (single quarter). Use instant periods (I suffix) for balance-sheet items: \"CY2023Q4I\" (snapshot at Q4 close)."
    },
    "unit": {
      "default": "USD",
      "description": "Unit of measure. Use \"USD-per-shares\" (or equivalently \"USD/shares\") for EPS, \"shares\" for share counts, \"pure\" for ratios. Ignored when concept resolves to a friendly name with a known unit.",
      "type": "string",
      "enum": [
        "USD",
        "USD-per-shares",
        "USD/shares",
        "shares",
        "pure"
      ]
    },
    "limit": {
      "default": 25,
      "description": "Number of companies to return.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Rank to start the page at, 0-based, over the sorted frame. Pass the next_offset from the previous response to read the next page — the ranked list is fetched whole and sliced, so paging is stable and gap-free. An offset at or past total_companies returns an empty page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "default": "desc",
      "description": "Sort direction. \"desc\" for highest values first (typical for revenue, assets). \"asc\" for lowest values.",
      "type": "string",
      "enum": [
        "desc",
        "asc"
      ]
    }
  },
  "required": [
    "concept",
    "period"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_compare_companies

Compare 2-10 named companies across 1-8 XBRL concepts, aligned on calendar periods. This is the middle shape between secedgar_get_financials (one company, one concept, full history) and secedgar_fetch_frames (one concept, one period, every reporting company) — reach for it when the question names the companies. One companyfacts read per company, resolved through the same frame dedup and tag priority as secedgar_get_financials so the numbers agree. Balance-sheet and entity-info concepts are filed as point-in-time values and align on the calendar year (annual) or quarter (quarterly) their snapshot falls in, so they sit in the same matrix as income-statement lines. The inline matrix covers the most recent periods up to `periods`, trimmed further when companies x concepts x periods is too large to return in one response; the full aligned series is materialized as df_<id> for growth rates and spreads — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query. A company that fails to resolve is reported in failed_companies and the comparison proceeds with the rest, and a company that does not report a concept is reported in gaps with the tags that were tried — never interpolated or zero-filled. Off-calendar filers and unit mismatches are surfaced in caveats rather than silently mixed.

Parameters5

companies	array	required	Companies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs.
concepts	array	required	Concepts to compare — friendly names like "revenue" or "net_income" (discover them with secedgar_search_concepts) or raw XBRL tags.
taxonomy	string	optional	XBRL taxonomy to resolve concepts under. Use ifrs-full only when every company in the list reports under IFRS; mixing IFRS and US GAAP filers in one call resolves them all under the same taxonomy.
period_type	string	optional	Align on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats.
periods	integer	optional	Upper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query.

Raw schema

{
  "type": "object",
  "properties": {
    "companies": {
      "minItems": 2,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "Ticker symbol or CIK number."
      },
      "description": "Companies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs."
    },
    "concepts": {
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "Friendly concept name or raw XBRL tag."
      },
      "description": "Concepts to compare — friendly names like \"revenue\" or \"net_income\" (discover them with secedgar_search_concepts) or raw XBRL tags."
    },
    "taxonomy": {
      "default": "us-gaap",
      "description": "XBRL taxonomy to resolve concepts under. Use ifrs-full only when every company in the list reports under IFRS; mixing IFRS and US GAAP filers in one call resolves them all under the same taxonomy.",
      "type": "string",
      "enum": [
        "us-gaap",
        "ifrs-full"
      ]
    },
    "period_type": {
      "default": "annual",
      "description": "Align on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats.",
      "type": "string",
      "enum": [
        "annual",
        "quarterly"
      ]
    },
    "periods": {
      "default": 4,
      "description": "Upper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query.",
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    }
  },
  "required": [
    "companies",
    "concepts"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_search_concepts

Search supported XBRL financial concepts by keyword, statement group, or taxonomy. Use before secedgar_get_financials or secedgar_fetch_frames to discover the right friendly name, or pass a raw XBRL tag (e.g., "NetIncomeLoss") to reverse-lookup which friendly names map to it. Empty search with no filters returns the full catalog.

Parameters3

search	string	optional	Case-insensitive substring matched against friendly name, label, and XBRL tags. Examples: "cash" finds cash and operating_cash_flow; "earnings" finds eps_basic and eps_diluted; "NetIncomeLoss" reverse-maps to net_income. Omit to list all concepts.
group	string	optional	Filter to a single financial statement group. income_statement covers P&L items; balance_sheet covers position items (use instant periods in secedgar_fetch_frames); cash_flow covers CF statement items; per_share covers EPS; entity_info covers DEI items like shares outstanding.
taxonomy	string	optional	Filter to a single XBRL taxonomy. us-gaap for US filers, ifrs-full for foreign filers, dei for entity info.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "description": "Case-insensitive substring matched against friendly name, label, and XBRL tags. Examples: \"cash\" finds cash and operating_cash_flow; \"earnings\" finds eps_basic and eps_diluted; \"NetIncomeLoss\" reverse-maps to net_income. Omit to list all concepts.",
      "type": "string"
    },
    "group": {
      "description": "Filter to a single financial statement group. income_statement covers P&L items; balance_sheet covers position items (use instant periods in secedgar_fetch_frames); cash_flow covers CF statement items; per_share covers EPS; entity_info covers DEI items like shares outstanding.",
      "type": "string",
      "enum": [
        "income_statement",
        "balance_sheet",
        "cash_flow",
        "per_share",
        "entity_info"
      ]
    },
    "taxonomy": {
      "description": "Filter to a single XBRL taxonomy. us-gaap for US filers, ifrs-full for foreign filers, dei for entity info.",
      "type": "string",
      "enum": [
        "us-gaap",
        "ifrs-full",
        "dei"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_dataframe_describe

List the dataframes (df_XXXXX_XXXXX) registered by the data-returning secedgar_* tools — any tool whose response carries a `dataset` handle stages its full result set here. Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, column schema, and whether the dataframe is truncated relative to the upstream source. Read the column schema here before writing SQL for secedgar_dataframe_query.

Parameters1

name

string

optional

Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all dataframes.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "description": "Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all dataframes.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

secedgar_dataframe_query

Run a single-statement SELECT against the canvas dataframes registered by the data-returning secedgar_* tools — any tool whose response carries a `dataset` handle. Inspect a dataframe with secedgar_dataframe_describe first; its column schema is what the SQL has to match. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied — list dataframes via secedgar_dataframe_describe. Optional register_as chains the result as a new dataframe with a fresh TTL.

Parameters4

sql	string	required	Single-statement SELECT against df_<id> tables on the shared canvas. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the names returned in fetch/search responses or listed by secedgar_dataframe_describe. BIGINT columns (e.g., XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — CAST(col AS DOUBLE) in projections for inline arithmetic.
register_as	string	optional	When set, persist the result as a new dataframe under this name (must match df_XXXXX_XXXXX shape, or pass a fresh df_<id> generated by the agent). Fresh TTL window — not inherited from the parents in the SELECT. Use to chain analyses without re-running the source SQL.
preview	integer	optional	Rows to include in the immediate response. Defaults to the row limit. Set lower (e.g., 50) when chaining via register_as and only a sample is needed inline.
row_limit	integer	optional	Hard cap on rows materialized in the response. Default 1000, max 10000. A query matching more rows than this stops at the cap and `row_count_capped` comes back true; the full result lives on-canvas under register_as when provided, so do not raise this to keep large results. One case is not detectable: a SQL LIMIT exactly equal to this cap reads identically to a result that genuinely holds that many rows, and is reported as exact.

Raw schema

{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "Single-statement SELECT against df_<id> tables on the shared canvas. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the names returned in fetch/search responses or listed by secedgar_dataframe_describe. BIGINT columns (e.g., XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — CAST(col AS DOUBLE) in projections for inline arithmetic."
    },
    "register_as": {
      "description": "When set, persist the result as a new dataframe under this name (must match df_XXXXX_XXXXX shape, or pass a fresh df_<id> generated by the agent). Fresh TTL window — not inherited from the parents in the SELECT. Use to chain analyses without re-running the source SQL.",
      "type": "string",
      "pattern": "^df_[A-Z0-9]{5}_[A-Z0-9]{5}$"
    },
    "preview": {
      "description": "Rows to include in the immediate response. Defaults to the row limit. Set lower (e.g., 50) when chaining via register_as and only a sample is needed inline.",
      "type": "integer",
      "minimum": 0,
      "maximum": 10000
    },
    "row_limit": {
      "default": 1000,
      "description": "Hard cap on rows materialized in the response. Default 1000, max 10000. A query matching more rows than this stops at the cap and `row_count_capped` comes back true; the full result lives on-canvas under register_as when provided, so do not raise this to keep large results. One case is not detectable: a SQL LIMIT exactly equal to this cap reads identically to a result that genuinely holds that many rows, and is reported as exact.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md28 KBView on GitHub

@cyanheads/secedgar-mcp-server

Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.

16 Tools (+1 opt-in) • 2 Resources • 1 Prompt

MCP SDK TypeScript

Public Hosted Server: https://secedgar.caseyjhand.com/mcp

Overview

SEC EDGAR filings, XBRL financials, and ownership data. No API key needed, only the User-Agent header SEC requires. Resolve companies by ticker, name, or CIK, search filings back to 1993, pull XBRL financials and cross-company comparisons by concept, and trace ownership through insider transactions, 13F holdings, 13D/13G blockholders, and fund portfolios. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`secedgar_company_search`	Find companies and retrieve entity info with optional recent filings
`secedgar_search_filings`	Search EDGAR filings since 1993: full text from 2001, archive browse before that
`secedgar_get_filing`	Fetch a filing's metadata and document text, paged or by section
`secedgar_get_financials`	Get historical XBRL financial data for one company and concept
`secedgar_get_snapshot`	One-call financial profile: the latest value of every supported concept
`secedgar_get_material_events`	8-K filings with item codes decoded and filterable
`secedgar_get_insider_transactions`	Form 4 / 4-A insider transactions parsed from ownership XML
`secedgar_get_institutional_holdings`	13F-HR quarterly holdings of one institutional manager
`secedgar_find_holders`	Reverse 13F lookup: which managers reported holding an issuer
`secedgar_get_beneficial_owners`	5%+ blockholders of an issuer from structured SCHEDULE 13D / 13G filings
`secedgar_get_fund_holdings`	ETF and mutual fund portfolio holdings from the quarterly NPORT-P report
`secedgar_fetch_frames`	One XBRL concept × one period across every reporting company
`secedgar_compare_companies`	Compare named companies across several concepts, aligned on calendar periods
`secedgar_search_concepts`	Discover supported XBRL concept names or reverse-lookup a raw tag
`secedgar_dataframe_describe`	List canvas dataframes with provenance, TTL, and schema
`secedgar_dataframe_query`	Run a single-statement SELECT across dataframes
`secedgar_dataframe_drop`	Drop a canvas dataframe by name; opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true`

Resources

Resource	Description
`secedgar://concepts`	XBRL financial concepts grouped by statement, mapping friendly names to XBRL tags
`secedgar://filing-types`	Common SEC filing types, plus the 8-K item-code tables for both numbering regimes

secedgar_search_concepts serves the same concept catalog to tool-only clients.

Prompts

Prompt	Description
`secedgar_company_analysis`	Structured analysis of a company's SEC filings: financial trends, risk factors, material events

Capability reference

`secedgar_company_search` _tool

query takes a ticker (equities, ETFs, and mutual funds; BRK-B or BRK.B), a current or former company name, or a CIK; include_filings (default on) adds up to filing_limit filings (1–50, default 10), filtered by exact forms match and filed_after / filed_before
Returns SIC code, exchanges, fiscal year end, and state of incorporation, plus series_id / class_id for a fund ticker; fails as no_match (near matches in data.suggestions) or multiple_matches
A date filter or an under-filled form filter scans past the recent window (the last year or 1,000 filings, whichever holds more) into the archive, up to 10 archive pages, and history_scanned_through reports how far it reached

`secedgar_search_filings` _tool

Full-text query (phrases, OR, -exclusion, wildcard*, ticker: / cik: scoping), or browse by forms and/or entity with no query; filed_after and filed_before must be given together; limit up to 100, and offset (up to 9,999) pages server-side only under sort: "relevance" on a 2001-onward search
Full text covers 2001 onward. Earlier ranges, back to 1993, come from the archives, and pre-2001 free text needs ticker: / cik: scope and reads up to 50 documents (scan reports candidates, scanned, and matched)
A range crossing 2001-01-01 is split and merged, each row tagged with source (efts, submissions, full-index); the response carries total, total_is_exact, and form_distribution

`secedgar_get_filing` _tool

accession_number in dash or 18-digit form, optional cik to speed the lookup, document for an exhibit, include_xbrl for XBRL artifacts; content_limit 1,000–200,000 characters per page (default 50,000)
Page with offset / next_offset until content_truncated is false, or jump with section (substring match on detected headings); the first page of a truncated document carries an outline of up to 50 headings with offsets
documents splits the filing into primary, exhibits, and auxiliary; entries marked binary (scans, PDFs, archives) fail as binary_document, and a section miss returns section_not_found with the outline
form, filing_date, and period_ending come from the company's submissions feed for a recent filing and from the filing's own SEC header for an older one

`secedgar_get_financials` _tool

company (ticker or CIK) plus concept as a friendly name or raw XBRL tag; taxonomy us-gaap (default), ifrs-full, or dei; period_type annual, quarterly, or all, defaulting to annual with a fallback to the full series for instant concepts; limit 1–100 trims the inline series
A deduplicated series, newest first, one value per calendar period with its source form, filed date, accession_number, and tag; tags_tried names the tags walked, and an empty result fails as no_concept_data, no_frame_data, or no_period_data
A concept that is neither a friendly name nor an UpperCamelCase tag fails as unknown_concept before any SEC request, with a formula for standard combinations (free_cash_flow, ebitda, working_capital) or up to three closest friendly names

`secedgar_get_snapshot` _tool

company, taxonomy us-gaap (default) or ifrs-full, and period_type annual, quarterly, or both (default); one companyfacts read covers every supported concept, and nothing is staged as a dataframe
Each lines entry reports the latest annual and quarterly value for a duration concept, or the latest instant value for balance-sheet and entity-info concepts, each with the tag it came from, under the line's taxonomy; concepts the filer doesn't report land in gaps with tags_tried

`secedgar_get_material_events` _tool

company plus up to 20 items codes, dotted (2.02) since 2004-08-23 and single integers (12) before; the two regimes don't overlap, so pair them across the changeover; filed_after / filed_before work alone and reach into the archive; limit 1–100 (default 20)
Each filing decodes its items to code, label, and regime (current / legacy); item_distribution counts every code in the window before the filter, and total_8k_scanned against total_matched shows what the filter removed
A date window reads every archive page overlapping it, up to 10; without one, the archive is read only to fill limit, stopping on the page that fills it; history_scanned_through and dataset.truncated report what went unread

`secedgar_get_insider_transactions` _tool

company is the issuer; transaction_type purchase (code P), sale (code S), or all (default); limit 1–100 (default 20); does not cover Forms 3 or 5
Without a date window it scans up to 100 of the newest Form 4 / 4-A filings; filed_after / filed_before (inclusive, either alone) read any period since mid-2003, paging into the archive (up to 10 pages) when the window predates the recent submissions window, and with a canvas every in-window filing is parsed, up to 100; history_scanned_through names the oldest filing parsed
Each transaction carries the reporting person, relationship, transaction_code and transaction_type, is_derivative, unsigned shares_traded with direction (acquire / dispose), price per share, and shares owned after; dataset.truncated flags Form 4 filings beyond those parsed

`secedgar_get_institutional_holdings` _tool

company is the 13F filer (a CIK is most reliable), not a portfolio company, which is secedgar_find_holders' job; quarter as YYYY-QN, defaulting to the newest filing; limit 1–500 (default 20) with offset / next_offset; consolidate (default true) merges sub-lines into positions sorted by value
A quarter older than the recent submissions window is found in the archive, read forward from the quarter end (up to 10 pages); a quarter the manager covered with a 13F-NT notice — or, with no quarter, a manager whose recent filings are notices only — fails as no_filings_found naming the notice's accession number and period
Holdings carry issuer, CUSIP, market_value_usd in whole USD, shares or principal, and put_call; total_holdings_in_filing counts raw rows and total_positions distinct positions; a shared legal name fails as ambiguous_entity

`secedgar_find_holders` _tool

issuer as a ticker, CIK, or name, plus an optional 9-character cusip, the precise match key (a name phrase-match both over- and under-matches); quarter as YYYY-QN, defaulting to the newest quarter past its 45-day filing deadline; limit 1–100 (default 20) from up to 500 fetched filings
Rows carry filer_cik, accession_number, and form, while search_mode (cusip / name), total_filings, fetched, and holders_in_quarter size the result; the list is unranked, so pass a filer_cik to secedgar_get_institutional_holdings to read the position

`secedgar_get_beneficial_owners` _tool

issuer is the company being held; form_kind all (default), 13D, or 13G; include_amendments (default true); limit 1–20 filings (default 10), each a separate document fetch
Each filing lists reporting_persons with voting power, dispositive power, and percent_of_class per person, which joint filers report for the same shares, so they don't sum; a 13D carries purpose_of_transaction, a 13G has none
Coverage starts 2024-12-18 with the structured XML schedules; legacy_filings_before_coverage counts the issuer's older SC 13D / SC 13G text filings

`secedgar_get_fund_holdings` _tool

fund as a ticker (VOO), series ID (S000002839), or CIK; series_id picks one fund of a multi-series trust, which otherwise fails as series_required with the series listed; report_date targets a period from available_report_periods; limit 1–100 (default 20) with offset / next_offset
Positions come largest first by percent_of_net_assets, with name, CUSIP / ISIN / LEI, balance and units, value_usd, and asset and issuer category, alongside fund net assets, total assets, and total liabilities
Holdings are as of report_period_date, roughly two months before filing_date; publication_lag_days states the gap

`secedgar_fetch_frames` _tool

concept as a friendly name or raw tag, period as CY2023, CY2024Q2, or CY2023Q4I, unit (default USD), sort desc / asc; limit 1–100 (default 25) with offset / next_offset down the ranking
One call queries one tag: unqueried_tags lists same-meaning variants to fetch separately, and related_tags lists alternate-definition tags some filers report instead
value_distribution.max_to_p95_ratio flags scale-factor outliers, period_end_range shows fiscal-year mixing, and caveats names the fiscal-Q4 gap in quarterly frames, the proxy-statement rows in annual NetIncomeLoss frames, and the 10-Q trailing-twelve-month rows an annual frame can hold while its year is still open
SEC publishes frames for us-gaap and dei tags only: taxonomy us-gaap (default) or dei picks the namespace for a raw tag (EntityCommonStockSharesOutstanding is dei), a friendly name keeps its own mapped taxonomy (shares_outstanding reads dei), and an explicit dei reads a friendly name's tags from dei, as in secedgar_get_financials; IFRS filers are read per company with taxonomy ifrs-full
A concept that is neither a friendly name nor an UpperCamelCase tag fails as unknown_concept before the frames request, with the same formula or closest-name hint as secedgar_get_financials; a well-formed tag with no frame is no_data

`secedgar_compare_companies` _tool

2–10 companies × 1–8 concepts; taxonomy us-gaap (default) or ifrs-full; period_type annual (default) or quarterly; periods 1–12 (default 4), trimmed further when the inline matrix gets too large
cells align each value on a calendar period and keep its frame, period_end, and source tag; failed_companies (reason not_found, ambiguous, or no_company_facts) and gaps (no value in any period) report what's missing, and caveats flag differing period ends, unit mismatches, and, once per concept, the companies whose values all predate the inline window, each with its newest period
A concept that is neither a friendly name nor an UpperCamelCase tag is listed once in unknown_concepts with its hint, never as a gap per company; the call fails as unknown_concept only when every concept is one
Inputs naming the same concept (revenue and Revenue, or one raw tag spelled twice) are compared once under the first spelling, with a caveat naming the merged inputs; a friendly name and a raw tag it maps to (revenue and Revenues) stay separate

`secedgar_search_concepts` _tool

search is a substring over friendly name, label, and tags, so a raw tag like NetIncomeLoss reverse-maps to its friendly name; group and taxonomy filter; no arguments returns the full catalog
Each concept lists tags, ifrs_tags (only where an IFRS element was confirmed in live 20-F filings), related_tags, unit, and group

`secedgar_dataframe_describe` _tool

Optional name for one dataframe; omit it to list the tenant's active dataframes, newest first
Each entry carries source_tool, query_params, created_at / expires_at, row_count, truncated, and the column_schema that SQL for secedgar_dataframe_query has to match

`secedgar_dataframe_query` _tool

One DuckDB SELECT in sql (joins, aggregates, window functions, CTEs); row_limit 1–10,000 (default 1,000), preview for fewer inline rows, and register_as (df_XXXXX_XXXXX) to save the result as a new dataframe
Returns columns, rows, row_count, and row_count_capped, which when true means row_count is the cap, not a total; BIGINT columns serialize as strings
Writes, DDL, file-reading functions, multiple statements, and system catalogs are rejected with typed reasons (non_select_statement, denied_function, multi_statement, system_catalog_access, and others)

`secedgar_dataframe_drop` _tool

name of the dataframe to drop; idempotent, returning dropped: false when nothing matched
Off unless EDGAR_DATAFRAME_DROP_ENABLED=true; disabled, it is absent from tools/list and uncallable, but still listed on the HTTP landing page with the flag that enables it

`secedgar://concepts` _resource

The friendly-name catalog grouped by statement, as text/markdown, with the us-gaap, IFRS, and alternate-definition tags for each concept
The names are what secedgar_get_financials, secedgar_compare_companies, and secedgar_fetch_frames accept as concepts

`secedgar://filing-types` _resource

Common SEC forms with cadence and use cases, as text/markdown
Includes the 8-K item-code tables for both numbering regimes, the vocabulary of secedgar_get_material_events' items filter

`secedgar_company_analysis` _prompt

Arguments: company required; focus_areas optional free text
Returns one user message with a numbered workflow (company search, a financial profile via secedgar_get_snapshot with trends via secedgar_get_financials, filing review, material events, and a peer comparison via secedgar_compare_companies with secedgar_fetch_frames for a market-wide ranking) and a findings template; insider, institutional, or blockholder terms in focus_areas add those ownership steps, and "ownership" adds all three

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

EDGAR-specific:

One process-wide queue paces SEC requests under the 10 req/s limit. A 429 is never retried: every SEC call is refused locally as rate_limited with a retryAfter countdown for EDGAR_RATE_LIMIT_COOLDOWN_SECONDS, then a single probe goes out. Reads served from the local mirror keep answering
CIK resolution from tickers (fund tickers included), current and former company names, or raw CIKs, with corporate-suffix normalization and near-match suggestions on a miss
Friendly XBRL concept names that handle historical tag changes. secedgar_get_financials, secedgar_get_snapshot, and secedgar_compare_companies share one frame dedup and tag priority, so their numbers agree; a period whose frame SEC assigned to a proxy statement's pay-versus-performance figure is answered from the filer's own report instead, an annual frame holding a 10-Q's trailing-twelve-month figure is left out of the annual series, and each reports caveats for calendar quarters missing from the frame-tagged series (SEC files fiscal Q4 only as the 10-K residual) and for series that stop years short
Filing documents converted from HTML to text, with heading detection and offset paging for oversized filings
Opt-in local SQLite mirror of company tickers and XBRL company-facts (EDGAR_MIRROR_ENABLED) that serves CIK resolution and financials from disk

Agent-friendly output:

In-conversation SQL: any tool whose response carries a dataset field has staged its full result as a DuckDB dataframe (df_<id>), while the inline list stays capped at limit; inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query
Discriminated outputs and explicit gaps: source on filing-search rows, search_mode, 8-K item regime, typed failed_companies reasons, and gaps with tags_tried in place of zero-filled values
Completeness disclosure: history_scanned_through, total_is_exact, publication_lag_days, and dataset.truncated tell agents how deep a scan went and what it left out
One parameter name per concept: company, filed_after / filed_before, and forms mean the same thing on every tool, and common alternate spellings (ticker, cik, start_date, end_date, form_types, and others) are accepted as aliases

Getting started

Public Hosted Instance

A public instance is available at https://secedgar.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "streamable-http",
      "url": "https://secedgar.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/secedgar-mcp-server@latest"],
      "env": {
        "EDGAR_USER_AGENT": "YourAppName your-email@example.com",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/secedgar-mcp-server@latest"],
      "env": {
        "EDGAR_USER_AGENT": "YourAppName your-email@example.com",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "EDGAR_USER_AGENT=YourAppName your-email@example.com",
        "ghcr.io/cyanheads/secedgar-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
A User-Agent string in SEC's "AppName contact@email.com" format; no account or key required.

Installation

Clone the repository:

git clone https://github.com/cyanheads/secedgar-mcp-server.git

Navigate into the directory:

cd secedgar-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env and set EDGAR_USER_AGENT

Configuration

Variable	Description	Default
`EDGAR_USER_AGENT`	Required. User-Agent sent to SEC, as `"AppName contact@email.com"`. SEC blocks IPs without one.	—
`EDGAR_RATE_LIMIT_RPS`	Max requests per second to SEC (1–10).	`10`
`EDGAR_RATE_LIMIT_COOLDOWN_SECONDS`	Seconds to refuse calls locally after a 429 before one probe goes out. SEC lifts a block only after ten quiet minutes, so a shorter value probes into it.	`600`
`EDGAR_TICKER_CACHE_TTL`	Seconds to cache the company and fund ticker files. A failed fund-file load is retried after a minute (or the rate-limit cool-down) instead of standing for the whole TTL.	`3600`
`EDGAR_DATASET_TTL_SECONDS`	Per-table TTL for canvas dataframes, a sliding window renewed on every dataframe operation.	`86400`
`EDGAR_DATAFRAME_DROP_ENABLED`	Set `true` to expose `secedgar_dataframe_drop`, the only destructive tool.	`false`
`EDGAR_MIRROR_ENABLED`	Enable the local SQLite mirror of company tickers and XBRL company-facts. Node/Bun only; bootstrap once with `bun run mirror:init`.	`false`
`EDGAR_MIRROR_PATH`	Directory holding the mirror databases.	`./data/edgar-mirror`
`EDGAR_MIRROR_REFRESH_CRON`	In-process refresh cron (HTTP transport only), e.g. `0 9 * * *`. Omit to refresh with `bun run mirror:refresh`.	—
`EDGAR_MIRROR_FALLBACK_LIVE`	Fall back to the live SEC API on a mirror miss. Set `false` for mirror-only reads.	`true`
`CANVAS_PROVIDER_TYPE`	Canvas engine; `none` disables dataframes.	`duckdb`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	HTTP server port.	`3010`
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.).	`info`

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run the production version:

bun run rebuild
bun run start:http   # or start:stdio

Run checks and tests:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

docker build -t secedgar-mcp-server .
docker run -e EDGAR_USER_AGENT="MyApp my@email.com" -p 3010:3010 secedgar-mcp-server

The image defaults to HTTP on port 3010 and ships the mirror CLI, so a running container can bootstrap and refresh its own mirror:

docker exec <container> bun run mirror:verify    # sync status + sample reads
docker exec <container> bun run mirror:init      # one-time bootstrap from the SEC bulk archive
docker exec <container> bun run mirror:refresh   # re-ingest after SEC rebuilds the archive

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point: registers resources and prompts, starts the SEC client, canvas, and optional mirror.
`src/config`	Server environment variable parsing and validation with Zod.
`src/mcp-server/tools/definitions`	Tool definitions (`*.tool.ts`) and the `buildToolDefinitions()` registration list.
`src/mcp-server/resources/definitions`	Resource definitions: XBRL concepts and filing types.
`src/mcp-server/prompts/definitions`	Prompt definitions: company analysis.
`src/services/edgar`	Paced SEC client, CIK resolution, XBRL concept mapping and series dedup, ownership / 13D / 13G / NPORT-P parsers, 8-K item tables, HTML-to-text.
`src/services/edgar/mirror`	Opt-in local SQLite mirror of company tickers and XBRL company-facts.
`src/services/canvas-bridge`	Adapter over the framework `DataCanvas`: `df_<id>` naming, per-table TTL, system-catalog SQL deny.
`scripts`	Build, devcheck, and lint tooling, plus the `mirror:*` commands.
`tests`	Unit and integration tests, mirroring the `src/` structure.

Development guide

See CLAUDE.md and AGENTS.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for logging, ctx.state for storage
Register new tools in buildToolDefinitions() (src/mcp-server/tools/definitions/index.ts), and resources and prompts in the createApp() arrays in src/index.ts
Wrap external SEC EDGAR calls: validate the raw response → normalize to a domain type → return the output schema; never fabricate a missing XBRL field — report it under gaps instead

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Install

Tools (16)

secedgar_company_searchsecedgar_search_filingssecedgar_get_filingsecedgar_get_financialssecedgar_get_snapshotsecedgar_get_material_eventssecedgar_get_insider_transactionssecedgar_get_institutional_holdings

Configuration

Environment variables

EDGAR_USER_AGENTrequired

User-Agent header for SEC compliance. Format: "AppName contact@email.com".

EDGAR_RATE_LIMIT_COOLDOWN_SECONDSdefault 600

Seconds to stop sending to SEC after a 429: calls are refused locally, then one probe request goes out.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_PUBLIC_URL

Public-facing origin override for TLS-terminating proxies (e.g., https://mcp.example.com). Leave unset for direct deployments.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "secedgar-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/secedgar-mcp-server@0.15.9"
      ],
      "env": {
        "EDGAR_USER_AGENT": "<YOUR_EDGAR_USER_AGENT>",
        "EDGAR_RATE_LIMIT_COOLDOWN_SECONDS": "600",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/secedgar-mcp-server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

secedgar_company_search

secedgar_search_filings

secedgar_get_filing

secedgar_get_financials

secedgar_get_snapshot

secedgar_get_material_events

secedgar_get_insider_transactions

secedgar_get_institutional_holdings

secedgar_find_holders

secedgar_get_beneficial_owners

secedgar_get_fund_holdings

secedgar_fetch_frames

secedgar_compare_companies

secedgar_search_concepts

secedgar_dataframe_describe

secedgar_dataframe_query

@cyanheads/secedgar-mcp-server

Overview

Tools

Resources

Prompts

Capability reference

secedgar_company_search tool

secedgar_search_filings tool

secedgar_get_filing tool

secedgar_get_financials tool

secedgar_get_snapshot tool

secedgar_get_material_events tool

secedgar_get_insider_transactions tool

secedgar_get_institutional_holdings tool

secedgar_find_holders tool

secedgar_get_beneficial_owners tool

secedgar_get_fund_holdings tool

secedgar_fetch_frames tool

secedgar_compare_companies tool

secedgar_search_concepts tool

secedgar_dataframe_describe tool

secedgar_dataframe_query tool

secedgar_dataframe_drop tool

secedgar://concepts resource

secedgar://filing-types resource

secedgar_company_analysis prompt

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`secedgar_company_search` _tool

`secedgar_search_filings` _tool

`secedgar_get_filing` _tool

`secedgar_get_financials` _tool

`secedgar_get_snapshot` _tool

`secedgar_get_material_events` _tool

`secedgar_get_insider_transactions` _tool

`secedgar_get_institutional_holdings` _tool

`secedgar_find_holders` _tool

`secedgar_get_beneficial_owners` _tool

`secedgar_get_fund_holdings` _tool

`secedgar_fetch_frames` _tool

`secedgar_compare_companies` _tool

`secedgar_search_concepts` _tool

`secedgar_dataframe_describe` _tool

`secedgar_dataframe_query` _tool

`secedgar_dataframe_drop` _tool

`secedgar://concepts` _resource

`secedgar://filing-types` _resource

`secedgar_company_analysis` _prompt