SEC Research MCP

Local SEC research tools for people and agents. You ask a question and get numbers, periods, sources, and a chart you can check. No paid data vendor and no hosted account for the core path.

Working name. Package and trademark checks are still open.

What it does

• Resolve a company from a ticker, CIK, or name

• Return financial series as decimal strings (missing is not zero)

• Extract filing text

• Render a line chart (SVG, PNG, CSV, Vega-Lite spec)

• Build a short evidence packet with coverage and accessions

Live EDGAR is the default. If SEC_USER_AGENT is unset, the runtime generates one. Set SEC_DEMO=1 for labeled Apple / Microsoft fixtures.

Related MCP server: Aegis Gov SEC Filings MCP

Install

Node.js 24+.

git clone https://github.com/ensp1re/sec-research-mcp.git
cd sec-research-mcp
npm install
npm run build

First run

npm run demo

That prints an evidence packet for AAPL revenue from fixtures. Then:

node apps/cli/dist/main.js doctor
node apps/cli/dist/main.js resolve AAPL
node apps/cli/dist/main.js filings AAPL 10-K
node apps/cli/dist/main.js financials AAPL revenue
node apps/cli/dist/main.js compare AAPL,MSFT revenue
node apps/cli/dist/main.js chart AAPL revenue
node apps/cli/dist/main.js filing AAPL
SEC_DEMO=1 node apps/cli/dist/main.js holdings AAPL
SEC_DEMO=1 node apps/cli/dist/main.js rulemaking
SEC_DEMO=1 node apps/cli/dist/main.js watch-create AAPL

Metrics in the demo set: revenue, net_income, cash, gross_margin, operating_cash_flow.

MCP (stdio)

Point an MCP client at the built server. Logs stay on stderr.

{
  "mcpServers": {
    "sec-research": {
      "command": "node",
      "args": ["apps/mcp/dist/server.js"],
      "cwd": "/absolute/path/to/sec-research-mcp"
    }
  }
}

HTTP (loopback): npm run api then GET /health, /v1/companies?q=AAPL, /v1/filings?q=AAPL, /v1/holdings?q=AAPL. Watch and job routes take Authorization: Bearer <key> (default local key local-dev, or SEC_API_KEY).

Tools: sec_coverage_get, sec_company_resolve, sec_filings_search, sec_filing_read, sec_filing_compare, sec_concepts_search, sec_financials_get, sec_companies_compare, sec_dataset_describe, sec_dataset_query, sec_dataset_export, sec_chart_create, sec_research_run, sec_holdings_get, sec_rulemaking_get, sec_watch_create, sec_watch_list, sec_watch_events.

Agents: copy skills/ into the client skills path. sec-research is the single-worker MCP workflow. sec-research-orchestrate splits resolve / numbers / filings / charts / critic across agents.

Live EDGAR

Live requests send a User-Agent. Set your own if you have one; otherwise the runtime generates sec-research-mcp/<id> (research; qa@localhost.invalid):

export SEC_USER_AGENT="YourName your@email.example"

SEC_DEMO=1 stays on fixtures. All outbound SEC traffic goes through one allowlisted broker (data.sec.gov, www.sec.gov, efts.sec.gov). Arbitrary URLs are rejected.

Rules the tools follow

• Every value has a unit, period, and source when it exists

• Missing, not applicable, parse failure, and incomplete coverage stay visible

• None of those states become 0

• Derived values (for example gross margin) are marked derived

Not in this release

Public IdP OAuth, production multi-tenant SaaS, object-storage vendors, investment advice, prices, and EDGAR filing submission. 13F holdings and rulemaking return sourced rows when the payload has them, otherwise explicit incomplete coverage.

Develop

npm test          # typecheck, lint, tests, harness validate
npm run lint:fix

Husky runs npm test on commit and push. See docs/product/PROJECT.md for product scope and docs/architecture/ARCHITECTURE.md for package boundaries.

License

Apache-2.0. LICENSE, NOTICE.