EDGAR 13F point-in-time

edgar13f-mcp

An MCP server that answers questions about SEC Form 13F holdings as they could have been known on a given date. It comes with an evaluation that was frozen before the server was written.

What it does, and why point-in-time matters

Institutional managers with US$100m or more in 13F securities file Form 13F every quarter, up to 45 days after the quarter ends. Many of them later amend the report. A restatement replaces the whole report. A new-holdings amendment adds rows to it. So "what did manager X hold at 2024-12-31?" has different correct answers on different days: nothing before the filing date, then the original report, and later the amended one.

A tool that always returns the latest version leaks the future into backtests, research notes and agent answers. This server takes an as_of date with every call and follows two rules (full text in contracts/CONTRACTS.md):

• Visibility (§3): a filing is visible on as_of only if its EDGAR filing date is on or before as_of. Nothing filed later affects the answer: not the rows, the citations, the filing list, or which filing counts as "latest".
• Amendments (§4): the visible filings for the period are put in order. The base is the last original or restatement. Every later new-holdings amendment is added to it. Each row cites the filing it came from.

Install and run

Python 3.11, with the official MCP Python SDK 2.x. The server speaks MCP over stdio only.

One command (needs uv). The package is edgar13f-mcp on PyPI, uploaded by this repository's release workflow with trusted publishing, and listed in the official MCP Registry as io.github.Serios16/edgar13f-mcp:

export SEC_USER_AGENT="Your Name your.email@example.com"   # required by SEC fair access

uvx --python 3.11 edgar13f-mcp # pin a release: edgar13f-mcp@1.2.2

For an MCP client such as Claude Desktop:

{"mcpServers": {"edgar13f": {

"command": "uvx", "args": ["--python", "3.11", "edgar13f-mcp"], "env": {"SEC_USER_AGENT": "Your Name your.email@example.com"}}}}

Any commit or tag also runs straight from GitHub: uvx --python 3.11 --from git+https://github.com/Serios16/edgar13f-mcp@v1.2.2 edgar13f-mcp. The older command name edgar13f-server still works. Both names are tested on the built wheel by tests/tools/install_smoke.sh (empty uv cache, MCP handshake; output in reports/artifacts/install_smoke_stage6.txt). From a clone instead:

python3.11 -m venv .venv && . .venv/bin/activate

pip install -e . export SEC_USER_AGENT="Your Name your.email@example.com" # required by SEC fair access python -m edgar13f.server # or: edgar13f-server

Environment variables:

• SEC_USER_AGENT: the User-Agent sent to sec.gov. It is required; without it the server does not contact sec.gov.
• EDGAR13F_CACHE_DIR: the on-disk cache. The default is $XDG_CACHE_HOME/edgar13f (or ~/.cache/edgar13f), then a private per-user temp dir. The server writes nowhere else.
• EDGAR13F_REDACT: set to exactly off to return the rows that are redacted by default (see Limits). Any other value, or none, keeps redaction on.
• EDGAR13F_AGENT_MODE: set to exactly on to cap unnarrowed holdings and diff answers at the 50 largest positions (see Agent use). Unset, every v1 call answers byte for byte as in v1.1.0.
• EDGAR13F_FIXTURE_DIR: serve recorded fixtures instead of EDGAR (used by the tests; refused together with EDGAR13F_REDACT=off).

SEC access follows the fair-access policy. Across processes that share a cache dir, request starts are spaced at least 0.25 s apart (under 5 per second). 403/429/5xx responses and HTML error pages trigger exponential backoff. Responses are cached on disk.

The tools

find_manager, period, issuer and max_positions come from Addendum A (additive: a call that uses none of them gets exactly the v1.1.0 answer).

Every response is a JSON object with the disclaimer *"13F reports long positions only; data may lag the period end by up to 45 days."* When the server cannot answer, it returns a normal result with status: "declined" and one of six reasons: unknown_cik, not_yet_filed, notice_only, invalid_period, invalid_argument, unsupported_request.

Agent use (Addendum A)

The extensions are meant for LLM agents, which usually start from a name and cannot read a 40 MB answer. A typical sequence:

// 1. name -> CIK (managers that have filed Form 13F come first)

{"tool": "find_manager", "arguments": {"name": "berkshire hathaway", "as_of": "2025-08-27"}} // 2. which filings make up one quarter, as of a date {"tool": "list_13f_filings", "arguments": {"cik": "1067983", "as_of": "2025-08-27", "period": "2025-03-31"}} // 3. one issuer only; the answer adds matched_cusips {"tool": "get_holdings_as_of", "arguments": {"cik": "1067983", "period": "2025-03-31", "as_of": "2025-08-27", "issuer": "apple"}} // 4. the 10 largest positions; the answer adds total_positions, truncated and order {"tool": "get_holdings_as_of", "arguments": {"cik": "1067983", "period": "2025-03-31", "as_of": "2025-08-27", "max_positions": 10}} // 5. the 20 largest changes by |value_delta| {"tool": "diff_holdings", "arguments": {"cik": "1067983", "period_a": "2024-12-31", "period_b": "2025-03-31", "as_of": "2025-08-27", "max_positions": 20}}

• issuer (2-100 characters) keeps rows whose issuer name contains it, ignoring case and runs of whitespace; it combines with cusip as AND.
• max_positions (1-200) ranks positions, i.e. (CUSIP, put/call, SH/PRN) groups, by summed value (holdings) or by |value_delta| (diff), and returns the top ones with all their rows. A position is never split, so a manager that files many rows per position can still return many rows; use issuer or cusip for one security.
• The new parameters only filter or order rows. Citations (accession_number, source_accessions, filing_date) and point-in-time behaviour are unchanged, and redaction happens before any filter.
• find_manager matches every current and former EDGAR name, returns EDGAR's current name, and is therefore not point-in-time for names. Its first call on an empty cache reads EDGAR's quarterly form indexes since 1993 (about a minute, once per cache directory); later calls take milliseconds.

With EDGAR13F_AGENT_MODE=on, a get_holdings_as_of or diff_holdings call that has none of cusip, issuer or max_positions is answered as if max_positions were 50, and the answer adds auto_limited: true. Every other call is unaffected. MCP client config:

{"mcpServers": {"edgar13f": {

"command": "uvx", "args": ["--python", "3.11", "edgar13f-mcp"], "env": {"SEC_USER_AGENT": "Your Name your.email@example.com", "EDGAR13F_AGENT_MODE": "on"}}}}

Limits

• Long positions only. Form 13F has no short positions, so position_type other than "long" is declined.
• Lag. Reports are due up to 45 days after quarter end, and amendments can arrive months later. An answer is only as current as what was filed by as_of.
• Redaction. By default, rows for gold ETFs/trusts, US energy-sector ETFs, S&P 500 index funds/ETFs, and UCITS copies of these are removed when the information table is parsed, because the author keeps a separate study blind to these instruments. They are then never returned, cached or logged. Matching uses issuer-name and title patterns plus a CUSIP list, and deliberately errs toward removing too much. Some ordinary securities are dropped too. Two concrete cases cost graded points: every "SPDR S&P ..." fund (any SPDR fund that names S&P, not only S&P 500 ones), and bonds of issuers named like a trust or fund whose class title carries a ".500" coupon (e.g. "5.500% NOTES"). An energy company whose class title says "UNIT" is another. Ruling D2 forbids narrowing the list to recover such points. A query for a removed CUSIP returns ok with no rows. Redaction applies to holdings rows; find_manager returns entity names unfiltered (ruling N1). To switch redaction off, set EDGAR13F_REDACT=off (exactly off); rows read that way are cached in a separate directory and never served once redaction is back on. See CLAUDE.md rule 2 and ruling D2 in REGISTER.md.
• The server does not cover pre-2013 text-format 13F filings, and it has no prices, charts or performance figures.

How it is evaluated

• Hidden, frozen grader. The gold sets, leakage set and grader were frozen in a separate private repository before any server code existed. The builder cannot read or write that repository. contracts/PREREG_COMMITMENT.md holds the SHA-256 of that repository's manifest and of the contract files copied here. Everything will be published after the final stage so the hash can be checked.
• Gold sets: 40 curated items and 700 generated items, stratified by case type (for example the day before and the day of a restatement), plus 3,114 leakage cases.
• Beyond the gates, the private repository also holds, each pre-registered before it ran: an out-of-sample set, an evaluation with an LLM agent in the loop, a diagnostic re-run of that evaluation, and a live capture around the Q3 2026 filing deadline (results below).
• Controls in this repository. They run in CI on every push, offline; the tests refuse sockets:
• a leakage suite with a *mutant* control (visibility check disabled; it must find violations, also for every Addendum A parameter and find_manager(as_of)) and a *no-op* control;
• blocklist proofs on synthetic rows, with a planted failure;
• an exhaustive check of the §4 amendment rules against an independent oracle, killed by each planted rule mutation (tests/unit/test_restatement.py);
• size, map and claims checks, each with a planted failure.
• OS-level isolation. CI runs the server as a separate unprivileged OS user from a read-only copy of the checkout. The job fails if that user creates any file or directory outside the expected cache dir, and a planted stray write must be caught (tests/tools/unprivileged_probe.sh).
• External cross-check (test time only). tests/tools/datasets_crosscheck.py compares answers for randomly sampled (cik, period, as_of) triples against the SEC Form 13F Data Sets. The server never reads the data sets.

Gate resul