[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_115":116},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module '@cyanheads/secedgar-mcp-server' is not configured","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":26,"_34":-5,"_35":36,"_37":-5,"_38":-5,"_39":40,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":48,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":-5,"_76":-5,"_77":48,"_78":-5,"_79":80,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90,"_91":92},"apiUrl","https://odel.app/api","creator","cyanheads","moduleId","secedgar-mcp-server","@cyanheads/secedgar-mcp-server","displayName","secedgar mcp server","tagline","Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.","iconKey","https://avatars.githubusercontent.com/u/10339515?v=4","category","data","status","published","metaDescription","metaKeywords","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://secedgar.caseyjhand.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363414000,"updatedAt",1781499625000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cyanheads%2Fsecedgar-mcp-server","sourceVerified",true,"importedAt","upstreamStars",6,"upstreamUpdatedAt",1781219544000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/cyanheads/secedgar-mcp-server","githubRepoFullName","cyanheads/secedgar-mcp-server","releaseId","ext-cyanheads-secedgar-mcp-server","version","0.11.0","descriptionMarkdown","

@cyanheads/secedgar-mcp-server

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

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

\n\n

\n\n[![npm](https://img.shields.io/npm/v/@cyanheads/secedgar-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/secedgar-mcp-server) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/secedgar-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n

\n\n

\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/secedgar-mcp-server/releases/latest/download/secedgar-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=secedgar-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvc2VjZWRnYXItbWNwLXNlcnZlciJdLCJlbnYiOnsiRURHQVJfVVNFUl9BR0VOVCI6IllvdXJOYW1lIHlvdXItZW1haWxAZXhhbXBsZS5jb20ifX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22secedgar-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/secedgar-mcp-server%22%5D%2C%22env%22%3A%7B%22EDGAR_USER_AGENT%22%3A%22YourName%20your-email%40example.com%22%7D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n

\n\n

\n\n**Public Hosted Server:** [https://secedgar.caseyjhand.com/mcp](https://secedgar.caseyjhand.com/mcp)\n\n

\n\n---\n\n## Tools\n\nEight tools for querying SEC EDGAR data, plus three for SQL analytics over the DuckDB-backed canvas dataframes those tools materialize:\n\n| Tool | Description |\n|:---|:---|\n| `secedgar_company_search` | Find companies and retrieve entity info with optional recent filings |\n| `secedgar_search_filings` | Full-text search across all EDGAR filing documents since 1993 |\n| `secedgar_get_filing` | Fetch a specific filing's metadata and document content |\n| `secedgar_get_financials` | Get historical XBRL financial data for a company |\n| `secedgar_get_insider_transactions` | Form 3/4/5 insider transactions (buys, sells, grants, exercises) parsed from ownership XML |\n| `secedgar_get_institutional_holdings` | 13F-HR quarterly institutional holdings parsed from the information table |\n| `secedgar_fetch_frames` | Fetch SEC XBRL frames for one concept × one period across all reporting companies |\n| `secedgar_search_concepts` | Discover supported XBRL concept names or reverse-lookup a raw tag |\n| `secedgar_dataframe_describe` | List canvas dataframes with provenance, TTL, and schema |\n| `secedgar_dataframe_query` | Run a single-statement SELECT across dataframes |\n| `secedgar_dataframe_drop` | Drop a canvas dataframe by name. Opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true` — off by default since TTL already handles cleanup |\n\n### `secedgar_company_search`\n\nEntry point for most EDGAR workflows — resolve tickers, names, or CIKs to entity details.\n\n- Supports ticker symbols (`AAPL`, `VOO`), company names (`Apple`), or CIK numbers (`320193`)\n- ETFs and mutual funds resolve by ticker via `company_tickers_mf.json`; fund results include `series_id` and `class_id` for downstream scoping\n- Current and former company names both resolve (`Facebook` → Meta Platforms, `Square` → Block)\n- Near-match suggestions on zero-result name search (e.g. `Microsfot` → `MICROSOFT CORP / MSFT`)\n- Optionally includes recent filings with form type filtering\n- Returns entity metadata: SIC code, exchanges, fiscal year end, state of incorporation\n\n---\n\n### `secedgar_search_filings`\n\nFull-text search across all EDGAR filing documents since 1993.\n\n- Exact phrases (`\"material weakness\"`), boolean operators (`revenue OR income`), wildcards (`account*`)\n- Entity targeting within query string (`cik:320193` or `ticker:AAPL`) — scoped server-side by CIK, so filings made under a former company name (same CIK) are included\n- Date range filtering, form type filtering, pagination up to 10,000 results\n- Returns form distribution for narrowing follow-up searches\n- When the entity-scoped window exceeds the inline limit, the already-fetched EFTS window is materialized as a `df_` dataframe — query it with `secedgar_dataframe_query`\n\n---\n\n### `secedgar_get_filing`\n\nFetch a specific filing's metadata and document content by accession number.\n\n- Accepts accession numbers in dash or no-dash format\n- Converts HTML filings to readable plain text\n- Configurable content limit (1K–200K characters, default 50K)\n- Can fetch specific exhibits by document name\n- **Offset paging** for large documents (10-K, S-1/A can exceed 1M chars): pass `next_offset` from a truncated response as `offset` on the next call to continue reading; first-page truncated responses include a detected `outline` (headings with offsets) for targeted navigation\n- **Section targeting** via the `section` param: jumps directly to a named heading by case-insensitive substring match (e.g. `\"risk factors\"`, `\"item 7\"`, `\"certain relationships\"`); on a miss, the error carries the detected outline so you can pick the correct heading\n- Extracted text is cached per `accession + document` (bounded LRU, 8 entries), making subsequent paged calls cheap\n\n---\n\n### `secedgar_get_financials`\n\nGet historical XBRL financial data for a company with friendly concept name resolution.\n\n- Friendly names like `\"revenue\"`, `\"net_income\"`, `\"eps_diluted\"` auto-resolve to correct XBRL tags\n- Handles historical tag changes (e.g., ASC 606 revenue recognition)\n- Automatic deduplication to one value per standard calendar period\n- Filter by annual, quarterly, or all periods\n- Optional `limit` caps the inline series to the most-recent N periods; the full series stays queryable via the `df_` dataframe\n- See `secedgar://concepts` resource for the full mapping\n\n---\n\n### `secedgar_get_insider_transactions`\n\nSurface Form 3/4/5 insider activity for a company by parsing ownership XML.\n\n- Reporting person, relationship to issuer (director, officer + title, 10% owner), and transaction date\n- Transaction code mapped to a readable type (purchase, sale, gift, award, exercise, …); shares signed by acquired/disposed\n- Price per share and shares owned after each transaction; covers non-derivative (open-market) and derivative (option/RSU) lines\n- Filter by `transaction_type` (`purchase`, `sale`, `all`); scans newest filings first\n- The full set of transactions parsed from the scanned recent filings is materialized as a `df_` dataframe (the inline list is a preview capped at `limit`) — query it with `secedgar_dataframe_query` to aggregate net buy/sell by insider\n\n---\n\n### `secedgar_get_institutional_holdings`\n\nSurface 13F-HR quarterly institutional holdings by parsing the information table.\n\n- Pass an institution (CIK or name) to see what it holds, or a company CIK to find its own 13F filings\n- Each holding: issuer name, CUSIP, market value (whole USD), shares/principal, and put/call; raw rows also carry investment discretion\n- Sub-lines for the same security (one per manager/account) are consolidated into distinct positions sorted by value by default — pass `consolidate: false` for raw filing rows\n- Resolves the filing-manager name and reporting quarter from the cover page; target a specific quarter with `quarter` (e.g. `\"2025-Q4\"`)\n- `total_holdings_in_filing` counts raw info-table rows; `total_positions` counts distinct positions after consolidation (both before `limit`)\n- The full parsed holdings set is materialized as a `df_` dataframe (the inline list is a preview capped at `limit`) — query it with `secedgar_dataframe_query` for full-filing aggregation or cross-quarter joins on `cusip` + `reporting_period`\n\n---\n\n### `secedgar_fetch_frames`\n\nFetch SEC XBRL frames for one concept × one period across all reporting companies.\n\n- Same friendly concept names as `secedgar_get_financials`\n- Supports annual (`CY2023`), quarterly (`CY2024Q2`), and instant (`CY2023Q4I`) periods\n- Inline response returns the top N ranked companies (sort + limit), with ticker enrichment\n- The full frames response (all reporters, typically 2k–10k rows) is materialized as a `df_` dataframe — query it with `secedgar_dataframe_query`\n- `related_tags` flags alternate-definition tags some filers use as their primary line (e.g. `cash` → restricted-cash-inclusive total, `equity` → NCI-inclusive total), so a whole-universe screen on the base tag isn't silently under-inclusive — query those separately\n\n---\n\n### `secedgar_search_concepts`\n\nDiscover supported XBRL concept names before querying financials or cross-company comparisons.\n\n- Search by friendly name, label, or raw XBRL tag\n- Filter by statement group (`income_statement`, `balance_sheet`, `cash_flow`, `per_share`, `entity_info`) or taxonomy\n- Reverse-lookup raw tags like `NetIncomeLoss` to the supported friendly names\n- Surfaces `related_tags` for concepts with a high-coverage alternate-definition tag (e.g. restricted-cash-inclusive cash) so callers can discover them before screening\n- Returns the same catalog used by `secedgar_get_financials`, `secedgar_fetch_frames`, and `secedgar://concepts`\n\n---\n\n### `secedgar_dataframe_describe` / `secedgar_dataframe_query` / `secedgar_dataframe_drop`\n\nIn-conversation SQL analytics over the dataframes that `secedgar_fetch_frames`, `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_get_insider_transactions`, and `secedgar_get_institutional_holdings` materialize on a shared DuckDB-backed canvas. Each data-returning call adds a `dataset` field with a `df_XXXXX_XXXXX` handle; pass that handle to `secedgar_dataframe_query` for joins, aggregates, window functions, percentiles — standard DuckDB SQL.\n\n- **Read-only by default.** Writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected by the framework SQL gate. System catalogs (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*`) are denied at the bridge layer so callers can't enumerate dataframes they don't already hold a handle for. `secedgar_dataframe_drop` is the only destructive tool and is opt-in (`EDGAR_DATAFRAME_DROP_ENABLED=true`); TTL handles cleanup otherwise.\n- **Per-table TTL.** Each dataframe ages on its own clock (default 24h, override with `EDGAR_DATASET_TTL_SECONDS`). The canvas itself uses the framework's sliding TTL.\n- **`register_as` chaining.** `secedgar_dataframe_query` can persist its result as a new dataframe (`df_XXXXX_XXXXX`) with a fresh TTL — pipe analyses without re-running the source query.\n\n## Resources\n\n| URI | Description |\n|:---|:---|\n| `secedgar://concepts` | Common XBRL financial concepts grouped by statement, mapping friendly names to XBRL tags |\n| `secedgar://filing-types` | Common SEC filing types with descriptions, cadence, and use cases |\n\n## Prompts\n\n| Prompt | Description |\n|:---|:---|\n| `secedgar_company_analysis` | Guides a structured analysis of a public company's SEC filings: identify recent filings, extract financial trends, surface risk factors, and note material events |\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Structured output schemas with automatic formatting for human-readable display\n- Unified error handling across all tools\n- Pluggable auth (`none`, `jwt`, `oauth`)\n- Structured logging with request-scoped context\n- Runs locally (stdio/HTTP) from the same codebase\n\nSEC EDGAR–specific:\n\n- Rate-limited HTTP client respecting SEC's 10 req/s limit with automatic inter-request delay\n- CIK resolution from tickers (including ETFs and mutual funds via `company_tickers_mf.json`), company names (current and former), or raw CIK numbers with local caching; near-match trigram suggestions on zero-result name queries; committed `former-names.json` asset for prior-name resolution (`Facebook` → Meta, `Square` → Block)\n- Friendly XBRL concept name mapping with historical tag change handling\n- Searchable concept catalog with statement-group metadata and reverse XBRL tag lookup\n- HTML-to-text conversion for filing documents via `html-to-text`\n- In-conversation SQL analytics: `secedgar_fetch_frames`, `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_get_insider_transactions`, and `secedgar_get_institutional_holdings` materialize their full result as a DuckDB-backed canvas dataframe queryable via `secedgar_dataframe_query`\n- No API keys required — SEC EDGAR is a free, public API\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://secedgar.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"secedgar-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://secedgar.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"secedgar-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/secedgar-mcp-server@latest\"],\n \"env\": {\n \"EDGAR_USER_AGENT\": \"YourAppName your-email@example.com\",\n \"MCP_TRANSPORT_TYPE\": \"stdio\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"secedgar-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/secedgar-mcp-server@latest\"],\n \"env\": {\n \"EDGAR_USER_AGENT\": \"YourAppName your-email@example.com\",\n \"MCP_TRANSPORT_TYPE\": \"stdio\"\n }\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/secedgar-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd secedgar-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Build:**\n\n```sh\nbun run build\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `EDGAR_USER_AGENT` | **Required.** User-Agent header for SEC compliance. Format: `\"AppName contact@email.com\"`. SEC blocks IPs without a valid User-Agent. | — |\n| `EDGAR_RATE_LIMIT_RPS` | Max requests/second to SEC APIs. Do not exceed 10. | `10` |\n| `EDGAR_TICKER_CACHE_TTL` | Seconds to cache the company tickers lookup file. | `3600` |\n| `EDGAR_DATASET_TTL_SECONDS` | Per-table TTL for canvas-registered dataframes. Sliding window touched on every dataframe op. | `86400` |\n| `EDGAR_DATAFRAME_DROP_ENABLED` | Set to `true` to expose `secedgar_dataframe_drop` — the only destructive tool on this server. Off by default; TTL handles cleanup. | `false` |\n| `EDGAR_MIRROR_ENABLED` | Enable the local SQLite mirror of `company_tickers` + XBRL company-facts so CIK resolution and financials read from disk instead of the live API. Node/Bun only (skipped on Workers). Bootstrap once with `bun run mirror:init`. | `false` |\n| `EDGAR_MIRROR_PATH` | Directory holding the mirror SQLite databases. | `./data/edgar-mirror` |\n| `EDGAR_MIRROR_REFRESH_CRON` | Cron for the in-process nightly refresh (HTTP transport only). Recommended `0 9 * * *`. Omit to refresh out-of-band via `bun run mirror:refresh`. | — |\n| `EDGAR_MIRROR_FALLBACK_LIVE` | When the mirror misses (not yet synced, or a filing newer than the last refresh), fall back to the live SEC API. Set `false` for strict mirror-only reads. | `true` |\n| `CANVAS_PROVIDER_TYPE` | Canvas engine. Defaults to `duckdb`; set to `none` to disable the canvas (e.g. when running on Cloudflare Workers, where DuckDB has no V8-isolate build). | `duckdb` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |\n| `MCP_HTTP_PORT` | HTTP server port | `3010` |\n| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n\n## Running the server\n\n### Local development\n\n- **Build and run the production version:**\n\n ```sh\n bun run rebuild\n bun run start:http # or start:stdio\n ```\n\n- **Run checks and tests:**\n ```sh\n bun run devcheck # Lints, formats, type-checks\n bun run test # Runs test suite\n ```\n\n### Docker\n\n```sh\ndocker build -t secedgar-mcp-server .\ndocker run -e EDGAR_USER_AGENT=\"MyApp my@email.com\" -p 3010:3010 secedgar-mcp-server\n```\n\nThe image ships the mirror CLI, so the local mirror (`EDGAR_MIRROR_ENABLED`) can be bootstrapped, inspected, and refreshed inside a running container:\n\n```sh\ndocker exec bun run mirror:verify # sync status + sample reads\ndocker exec bun run mirror:init # one-time bootstrap (downloads the SEC bulk archive)\ndocker exec bun run mirror:refresh # re-ingest when the archive has been rebuilt\n```\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). Eight SEC EDGAR tools plus three `dataframe_*` tools for SQL analytics. |\n| `src/mcp-server/resources/definitions/` | Resource definitions. XBRL concepts and filing types. |\n| `src/mcp-server/prompts/definitions/` | Prompt definitions. Company analysis prompt. |\n| `src/services/edgar/` | SEC EDGAR API client, XBRL concept mapping, HTML-to-text conversion. |\n| `src/services/canvas-bridge/` | Adapter over the framework `DataCanvas`: `df_` minting, all-nullable schema derivation, per-table TTL bookkeeping, bridge-layer system-catalog SQL deny. |\n| `src/config/` | Server-specific environment variable parsing and validation with Zod. |\n| `tests/` | Unit and integration tests, mirroring the `src/` structure. |\n\n## Development guide\n\nSee [`CLAUDE.md`](https://github.com/cyanheads/secedgar-mcp-server/blob/main/CLAUDE.md) and [`AGENTS.md`](https://github.com/cyanheads/secedgar-mcp-server/blob/main/AGENTS.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for logging, `ctx.state` for storage\n- Register new tools and resources in the `createApp()` arrays\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the [LICENSE](https://github.com/cyanheads/secedgar-mcp-server/blob/main/LICENSE) file for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Data & Analytics","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":104},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[19,105,106,107,108,109,110,111,112,113,114],"license","Apache-2.0","language","TypeScript","registryName","io.github.cyanheads/secedgar-mcp-server","homepage","https://www.npmjs.com/package/@cyanheads/secedgar-mcp-server","edgar","filings","financial-data","mcp","mcp-server","model-context-protocol","sec","sec-edgar","typescript","xbrl","ENV",{"_117":118,"_119":120,"_121":122},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]