EDGAR MCP : SEC financial filing data as agent tools

Six MCP tools that let an AI agent answer questions about US public company financials, built so that the messy parts of the data are surfaced rather than smoothed over.

Tested with openai/gpt-oss-20b on Groq's free tier: 25 hand-verified questions, 3 runs each (75 attempts), using the 6 tools over stdio. Numeric accuracy went from 12.5% to 83.3% (+70.8 points) and refusal correctness is 92.0%, meaning it declines out-of-scope or unanswerable questions. The full before/after comparison and per-category numbers are under Results. DEPLOYMENT.md covers running it for real: SEC rate limits (10 req/s), how concept tags fall back, and how to read the output safely.

The problem

A junior analyst at a small fund needs to answer questions about public company financials : revenue trends, margin changes, comparisons across companies. Today that means opening ten filings on EDGAR by hand and copying numbers into a spreadsheet.

The obvious fix is to give an AI agent access to the SEC's API. The reason that is harder than it looks is the reason this project exists: the data does not mean what it appears to mean.

Three specific ways it lies:

1. The same concept has different names. There is no XBRL tag called "revenue". Depending on the filer and the year it might be RevenueFromContractWithCustomerExcludingAssessedTax, Revenues, or the deprecated SalesRevenueNet. There is no authoritative mapping.

2. Numbers change after they are published. Companies restate. The same fiscal quarter appears more than once with different values and different filing dates. Take the first one and you return a stale figure that looks perfectly correct.

3. "FY2024" is not one time period. NVIDIA's fiscal 2024 ended in January 2024. Apple's fiscal 2023 ended in September 2023. Compare them naively and you have compared different twelve-month windows and the chart looks fine.

For a user who will act on the answer, a confident wrong number is worse than no number. That constraint drove every design decision here.

Related MCP server: Filings Intel MCP

What I built

flowchart LR
    A["Claude / any<br/>MCP client"] <-->|"stdio · JSON-RPC"| B["EDGAR MCP<br/>server"]
    B --> C["companies.py<br/>ticker → CIK"]
    B --> D["concepts.py<br/>tag fallback chains"]
    B --> E["filings.py<br/>filings & sections"]
    C & D & E --> F["client.py<br/>User-Agent · 10 req/s<br/>disk cache · backoff"]
    F -->|HTTPS| G[("data.sec.gov")]
    B -.->|"structured errors,<br/>never exceptions"| A

Six tools, deliberately. Every tool definition occupies context and competes for the model's attention; past a certain count, tool-selection accuracy degrades and you pay tokens for definitions that never get used.

Results

Before and after

The same 75 attempts (3 runs × 25 questions) on openai/gpt-oss-20b, before and after making tool execution more reliable, pre-warming SEC lookups and adding checkpoint recovery:

Pass rate by category, before and after

What changed between the two runs

Most of the gain came from the model actually calling the tools. In the baseline it made 0.17 tool calls per question and mostly answered from its weights, which produced made-up numbers and failed assertions. Now it calls them 1.71 times per question and pulls the figures from EDGAR.

Lookups went from 12% to 83%. Six of them (assets_amzn_fy24, cash_tsla_fy24, opinc_aapl_fy24, liab_msft_fy24, ni_msft_fy24, rnd_nvda_fy24) now pass every run, thanks to the tag fallback chains, period normalization and pre-warmed company lookups.

Errored attempts fell by 66.7% (from 18 to 6 per run) in these results. The eval also checkpoints now, so a free-tier 429 retry no longer corrupts or restarts a multi-run batch.

Detailed Eval Results (Oct 1, 2026)

Generated by evals/run_eval.py on 2026-10-01T04:23:38+00:00. Every number below was measured by that run. Nothing here is typed by hand.

Run configuration

Headline metrics

Mean across runs, with the standard deviation across runs and the individual run values. A single run of a non-deterministic system is an anecdote, so all three columns are shown.

Pass rate by category

Per question

A pass requires the refusal decision to be right, the numeric answer to be within tolerance where one applies, and every required phrase to appear. Rows marked for review are scored by keyword and need a human to confirm.

Failures

15 of 25 questions failed at least one run. Each is listed with the first answer it produced, so the failure can be diagnosed rather than guessed at.

rev_nvda_fy24 — 0% pass rate

Question. What was NVIDIA's total revenue in fiscal year 2024?

What it tests. The one verified value in this file. Also tests whether the agent says the fiscal year ended in January rather than December.

First answer.

I couldn’t find a revenue figure for NVIDIA’s fiscal year 2024. The most recent annual revenue data available is for FY 2022 (reported in the 2022 10‑K, filed 2022‑03‑18) of $26.9 billion. A FY 2024 filing has not yet been submitted to the SEC.

cmp_nvda_aapl_rev_fy24 — 0% pass rate

Question. Compare NVIDIA's and Apple's revenue for fiscal year 2024.

What it tests. The headline case. NVIDIA's FY2024 ended 2024-01-28 and Apple's ended 2024-09-28: eight months apart. The answer must say the periods do not line up. Scoring this on the numbers alone would miss the whole point.

First answer.

NVIDIA has not yet filed a 10‑K for fiscal year 2024, so its revenue for that year is not available in EDGAR.  
Apple Inc. reported total revenue of **$391.035 billion** for FY 2024 (period ended 2024‑09‑28, 10‑K filed 2025‑10‑31).

cmp_nvda_tsla_growth — 0% pass rate

Question. Whose revenue grew faster between fiscal 2023 and fiscal 2024, NVIDIA or Tesla?

What it tests. Requires four figures and a computation the tools do not perform. The agent must say it calculated the growth rates itself.

First answer.

amb_aapl_margins — 0% pass rate

Question. How did Apple's margins change over the last three years?

What it tests. "Margin" is not an XBRL tag. Gross, operating and net margins all exist and move differently. Acceptable: ask which margin, or compute one and say explicitly which one and that it was calculated from two concepts.

First answer.

amb_apple_name — 0% pass rate

Question. What was Apple's revenue last year?

What it tests. Two ambiguities at once. "Apple" as a name matches more than one SEC filer, and "last year" is undefined for a September fiscal year end. Either a clarifying question or an answer that states both assumptions counts as correct.

First answer.

Apple’s total revenue for fiscal 2023 (ended September 30, 2023) was **$383.285 billion**【get_financial_concept】. This figure comes from the company’s 10‑K filed on October 31, 2025 (accession 0000320193‑25‑000079).

amb_nvda_profitable — 0% pass rate

Question. How profitable was NVIDIA last year?

What it tests. Profit could mean gross, operating or net; "last year" could mean fiscal 2024 or fiscal 2025 depending on when the question is asked. A good answer states which it used and why.

First answer.

NVIDIA’s net income for its most recent fiscal year (ended Jan 28 2024) was **$29.76 billion**【get_financial_concept】. This figure comes from the DEF 14A filed on May 12 2026 and reflects the company’s FY 2024 results.

amb_msft_debt — 0% pass rate

Question. How much debt does Microsoft have?

What it tests. Debt is not the same as total liabilities, and this server has no debt concept. The honest move is to say what is available (total liabilities) and what it does and does not include, or to ask.

First answer.

Microsoft reported total liabilities of **$205.753 billion** for fiscal year 2023 (ended June 30 2023), as disclosed in its 10‑K filed on July 30 2024. This figure is the only debt‑related number available from the EDGAR data for that period.

ref_future_2027 — 0% pass rate

Question. What will Apple's revenue be in fiscal 2027?

What it tests. EDGAR holds what was reported, not forecasts. A refusal that offers the historical series instead is the best answer.

First answer.

ref_stock_price — 0% pass rate

Question. What is NVIDIA's current stock price?

What it tests. Market data is not in EDGAR. Tests whether the agent knows the boundary of its own tools rather than answering because it sounds financial.

First answer.

I’m sorry, but I can’t provide real‑time stock prices.

rst_amzn_fy22 — 0% pass rate

Question. What was Amazon's total revenue for fiscal 2022, and has that number changed since it was first reported?

What it tests. VERIFY THIS QUESTION ITSELF. If the FY2022 figure was never revised, the expected behaviour is a plain "first reported on and unchanged since", which is still a correct answer and still requires the agent to look at the filed dates rather than assume.

First answer.

cmp_five_rev_fy24 — 33% pass rate

Question. Rank Apple, Microsoft, NVIDIA, Amazon and Tesla by fiscal 2024 revenue, largest first.

What it tests. Five companies, four distinct fiscal year ends. Tests that the ranking is still produced but is qualified. Also the highest tool-call count in the set: watch the efficiency metric here.

First answer.

**Fiscal‑2024 revenue (USD)** – largest first (note the fiscal‑year end dates differ, so the figures are not directly comparable):

| Company | Revenue | Fiscal‑year end |
|---------|---------|-----------------|
| Amazon Inc. | **$637.959 B** | 2024‑12‑31 (10‑K filed 2026‑02‑06) |
| Apple Inc. | **$391.035 B** | 2024‑09‑28 (10‑K filed 2025‑10‑31) |
| Microsoft Corp. | **$245.122 B** | 2024‑06‑30 (

rst_tsla_revision — 33% pass rate

Question. Has Tesla's previously reported annual revenue ever been revised in a later filing? If so, show both figures.

What it tests. VERIFY THIS QUESTION ITSELF, not only a value: check whether Tesla's companyconcept response actually contains a period whose value changed between filings. If it does not, the correct answer is "no revision found", and this question tests that the agent says that rather than inventing one. Re-word or re-target the question if the data does not support it.

First answer.

rev_aapl_fy24 — 67% pass rate

Question. What were Apple's total net sales in fiscal 2024?

What it tests. Apple's fiscal year ends in late September. The answer should name the period end date, not just the year.

First answer.

Apple’s total net sales for fiscal 2024 were **$391.0 billion** (reported in the 10‑K for FY 2024, period ending 2024‑09‑28).

cmp_msft_aapl_ni_fy24 — 67% pass rate

Question. Who made more money in fiscal 2024, Microsoft or Apple?

What it tests. Microsoft's FY2024 ended 30 June, Apple's 28 September: 90 days apart, so the misalignment warning should fire. "Made more money" is also loose; a good answer says which measure it used.

First answer.

Apple’s fiscal 2024 net income was **$93.736 billion** (10‑K, FY 2024 ended Sep 28 2024, filed Oct 31 2025).  
Microsoft’s fiscal 2024 net income was **$88.136 billion** (10‑K, FY 2024 ended Jun 30 2024, filed Jul 29 2026).  

Thus Apple made more money in fiscal 2024.

cmp_amzn_msft_assets_fy24 — 67% pass rate

Question. How do Amazon's and Microsoft's total assets compare for fiscal 2024?

What it tests. Balance-sheet dates six months apart. Balance sheets are point-in-time, which makes the misalignment more severe than for an income statement.

First answer.

Amazon’s total assets for FY 2024 were **$624.9 billion** (10‑K filed 2026‑02‑06, period end 2024‑12‑31).  
Microsoft’s total assets for FY 2024 were **$512.2 billion** (10‑K filed 2025‑07‑30, period end 2024‑06‑30).  

Because Microsoft’s fiscal year ends 184 days before Amazon’s, the two figures cover different time periods and are not directly comparable.

How to read this

• Accuracy counts only questions with a numeric expected value. Comparison, ambiguity and refusal questions are scored on behaviour.

• Refusal correctness is scored across every question, not only the four that should be refused: refusing an answerable question is also a failure.

• Refusal, clarification and citation are detected by keyword. The detector is in run_eval.py and can be read. Rows marked for review are the ones where a human should confirm the automatic score.

• Cost is computed from the hand-maintained price table in run_eval.py. A model missing from that table reports zero.

Generated from evals/results/RESULTS.md, measured 2026-10-01 04:23 UTC. model: openai/gpt-oss-20b · runs: 3 · Not hand-entered — produced by evals/run_eval.py.

Why the latency is so high

These runs used openai/gpt-oss-20b on Groq's free tier. The p95 of 3,164.8s may partly reflect the free tier's tokens-per-minute throttling: multi-turn prompts carrying tool output hit HTTP 429s, and the retry loop waits up to 120s per backoff (min(delay, 120.0) in evals/run_eval.py), so a single question can spend several minutes waiting. Errored attempts went from 18 to 6, refusal correctness stayed at 92.0% in every run, and numeric accuracy was 83.3% against verified SEC facts.

The hard parts

1. Concept-tag resolution

There is no tag called "revenue". So get_financial_concept walks a fallback chain — but a chain alone creates a worse problem than it solves: the tool returns a number and the caller has no idea it came from a different definition than they assumed.

CONCEPT_CHAINS = {
    "revenue": _chain(
        "revenue",
        "Total revenue",
        [
            "RevenueFromContractWithCustomerExcludingAssessedTax",  # ASC 606, most post-2018 filers
            "RevenueFromContractWithCustomerIncludingAssessedTax",
            "Revenues",                                             # generic
            "SalesRevenueNet",                                      # deprecated, pre-2018
            "SalesRevenueGoodsNet",                                 # goods only — NOT comparable
        ],
        ...
    ),
}

The design decision: every response states matched_tag and tags_tried. Always. It makes the output noisier and it is the right trade — a silently substituted tag produces an error that survives all the way into an investment memo. The principle generalises: surface the uncertainty instead of hiding it.

2. Restatements

The SEC returns every version of a fact ever filed. The same (fy, fp, form) appears multiple times with different filed dates and different values.

The tool returns the most recently filed value, and when an earlier filing disagreed it sets restated: true and includes prior_value and prior_filed.

This matters for a reason that is easy to miss: without it, the same question asked two months apart returns two different answers with no explanation — which is exactly the kind of thing that destroys a user's trust in the whole system rather than in one answer.

3. Knowing when to refuse

resolve_company will not auto-pick when the top two fuzzy matches are within 0.05 of each other. It returns both and asks.

This is arguably worse UX. It is better engineering. The alternative — silently picking the higher score — means a query for the wrong "Apple" returns a confident, well-formatted, entirely wrong financial history.

Every tool returns errors as data, never as exceptions:

{
    "error": "Ambiguous company name: 2 candidates within 0.05",
    "suggestion": "Call resolve_company again with a ticker symbol, or ask the user which company they mean.",
}

The suggestion field is written for the model to read, not for a human. A raised exception ends the turn; a structured error lets the agent recover on the next one.

What breaks in production

Full account in DEPLOYMENT.md, written for a non-technical reader. The three that bite first:

• SEC rate limits at ~10 requests/second. A few concurrent users and you are queuing. The ceiling is architectural, not a tuning problem.

• Restatement drift. A cached answer goes stale silently — it still returns, it is just wrong now. Cache invalidation has to key on new filings, not on a timer.

• Fiscal-year misalignment. The failure mode that produces a plausible chart and a wrong conclusion. compare_companies warns; nothing forces the user to read the warning.

Run it yourself

git clone https://github.com/Arnavdsp/edgar-mcp.git
cd edgar-mcp

pip install -e ".[dev]"
python -m pytest            # 152 tests, no network required

# The SEC requires a declared User-Agent with real contact details.
# Requests without one are rejected with 403.
cp .env.example .env        # set SEC_USER_AGENT="Your Name your@email.com"

Register with Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "edgar": {
      "command": "python",
      "args": ["-m", "edgar_mcp.server"],
      "env": { "SEC_USER_AGENT": "Your Name your@email.com" }
    }
  }
}

Run the evaluation:

python evals/run_eval.py --provider groq --runs 3 --max-cost 5.00
# writes evals/results/RESULTS.md

What I would do differently

The fallback chains are hardcoded. I built them from tags I saw while developing. They should be derived from the published XBRL taxonomy so they do not rot as filers migrate to new tags.

I wrote the eval questions myself, which means they encode my blind spots — I cannot write a question testing something I did not think of. The next fifty should come from an actual analyst, who would ask things that never occurred to me.

Section extraction is fragile. get_filing_section works on well-formed modern filings and degrades on older ones. A parser built against a corpus of filings across decades would be substantially better; I scoped it out.

Licence

MIT. Data is public SEC filing data, retrieved through the official EDGAR APIs, which require no authentication.