Skip to main content
Glama
kodros-sec-edgar-mcp

kodros-sec-edgar-mcp

kodros-sec-edgar-mcp

A read-only MCP server that gives an AI assistant numbers from SEC EDGAR filings. Every figure comes back with the filing it came from: accession number, form, filed date and XBRL tag.

Part of the Kodros local AI stack.

How it works

flowchart LR
  Client[MCP client: Claude, Hermes, OMP] -->|stdio| Server[server.py: 18 fs_* tools]
  Server --> Core[core.py: HTTP, cache, EDGAR normalizing]
  Core -->|8 req/s, contact User-Agent| SEC[sec.gov and data.sec.gov]
  Core --> Cache[(disk cache)]
  Collector[sec-edgar-collect CLI] --> Signals[signals_sec.py, signals_mkt.py]
  Signals --> DB[(SQLite signal store)]
  Outcomes[outcomes.py: 1/5/10/20 day forward returns] --> DB
  Server --> DB

core.py has no MCP imports, so it tests offline. The tools cover company lookup, reported XBRL series with restatements flagged, a fundamentals snapshot, side-by-side comparison of up to 8 companies, reading one Item of a filing, Form 4 insider trades, price history and a DCF calculator that fetches nothing. A collector sweeps the EDGAR daily index and grades each signal type against an equal-weight control. No language model sits in the data path. Missing data comes back as null, never zero.

Related MCP server: filingrail-mcp

Stack

Python 3.12, FastMCP 3, httpx, defusedxml for filing XML, SQLite, uv, pytest.

Run

uv sync
export SEC_EDGAR_USER_AGENT="my-app you@example.com"   # required by the SEC
uv run pytest
uv run sec-edgar-mcp                                     # stdio MCP server
uv run sec-edgar-collect sec --days 2                    # fill the signal store

MCP client config:

{ "mcpServers": { "sec-edgar": {
  "command": "uv", "args": ["run", "--directory", "/path/to/kodros-sec-edgar-mcp", "sec-edgar-mcp"],
  "env": { "SEC_EDGAR_USER_AGENT": "my-app you@example.com" } } } }

Optional: SEC_EDGAR_CACHE (default ~/.cache/sec-edgar-mcp) and SEC_EDGAR_DB (default ~/.local/share/sec-edgar-mcp/signals.db).

Status and limits

  • Version 0.1.0. The offline test suite covers the math, signal scoring, XML entity rejection and outcome grading. Live smoke scripts in tests/ need network.

  • Requests to sec.gov are throttled to about 8 per second, under the SEC limit of 10.

  • Price data uses Yahoo's unofficial chart endpoint, which can change without notice. Prediction market reads use public Polymarket and Kalshi APIs.

  • The signal universe is today's liquid tickers, so backtests carry survivorship bias.

  • No order, transfer or account tools. Output is research data, not investment advice.

License

Copyright 2026 Tanner Osterkamp. All rights reserved. See LICENSE. The source is public to read; ask before reuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Give your AI agent live SEC EDGAR data: company financials, insider trades, 8-K events, 13F holdings, and the raw filings stream — all normalized to clean JSON, every number traceable back to its sec.gov source filing.
      8
      43 PyPI
      MIT