2.1.1
on PyPI
MCP server · XBRL · v2.1.1
arelle-mcp
Puts XBRL filings — load, validate, extract, render, compare — behind 46 MCP tools, with the Arelle processor doing the XBRL work.
pip install arelle-mcp
46
tools, counted from the registry
16
tests, run before publish
Apache-2.0
license
What it is
arelle-mcp gives a language model access to XBRL financial data through 46 tools: load and validate a filing, extract facts by concept, period, dimension or unit, walk the presentation and calculation trees, read the narrative sections, and render a statement. Arelle — the free, open-source XBRL-certified processor — is the engine underneath.
Specification
| Property | Value |
|---|---|
| Protocol | Model Context Protocol — stdio and HTTP |
| Engine | Arelle (XBRL-certified processor) |
| Tools | 46, read from the live registry at import time |
| Also exposes | 5 resources and 5 prompt templates |
| Validation profiles | SEC EFM, EU ESEF, UK HMRC, generic |
| Sources | Local files, URLs, and SEC EDGAR by ticker or CIK |
| Python | 3.10 and above |
| Dependencies | mcp[cli], arelle-release, httpx, pydantic — each capped below its next major |
| Tests | 16, run before publish |
| License | Apache-2.0 |
Recorded session
A recorded terminal session for this package is pending. Until one is captured against the published release, the checkable claim on this page is the tool count: the number below is read from the live registry, and the package's own test fails if the README disagrees with it.
How it works
Two things on this page are mechanically enforced: what stdout is reserved for, and where the tool count comes from.
The wire
stdout is the protocol
Under the stdio transport, stdout is the JSON-RPC channel. One stray byte on it ends the session.
P1
The failure this fixed
Arelle at its defaults printed iXBRL namespace and validation messages to stdout while loading a filing. That desynced the framing: clients reported a JSON parse error on an Arelle log token, then a closed connection, and every in-flight tool call was lost.
JSON Parse error: Unexpected identifier "ix11" MCP error -32000: Connection closed
Guard
Three independent levels reserve it
The real stdout is duplicated to a private descriptor and file descriptor 1 is re-pointed at stderr, so even a C-level write is safe. Then sys.stdout is replaced by a proxy whose buffer is that private descriptor while every text write goes to stderr. Then the Arelle logger is pinned to stderr with propagation off.
os.dup2(sys.stderr.fileno(), stdout_fd) sys.stdout = _ProtocolStdout(protocol, sys.stderr)
Kept
Nothing is silenced
Every diagnostic still exists — it moves to stderr, where the client shows it. A test proves the channel is clean end to end rather than asserting it in a comment.
tests/test_stdout_is_clean.py
The count
The number comes from the registry
One release shipped four different tool counts in four places. None of them matched the code.
Drift
Four numbers, one truth
A previous release stated 12 tools in the package docstring, 17 in the README, 31 in the server instructions and 47 in the startup log — against 46 actually registered. Correcting the strings would have drifted again within a month.
docstring 12 · README 17 · instructions 31 startup log 47 · registry 46
Assert
The README is now checked against the code
The count is read from the live registry, and a test fails the build if the README disagrees. You can run the same one-liner against any checkout and get the number this page states.
python -c "import asyncio; from arelle_mcp.server import mcp; \ print(len(asyncio.run(mcp.list_tools())))"
Limits
What this does not do, and where it should not be trusted. These stay on the page whatever else changes.
This is not a licensed or redistributable market-data product. It reads what you point it at — your own files, a URL, or SEC EDGAR — and it ships no data of its own.
The XBRL work is Arelle's. Validation profiles, taxonomy handling and calculation checks are that processor's behaviour, and its limits are this package's limits.
Loading a large filing costs memory and time, and the number of concurrently loaded filings is capped by configuration rather than by anything clever.
Fetching from SEC EDGAR reaches the network from your machine, under SEC's rate limits and your own user agent. Nothing is cached for you and nothing is proxied.
The tests run the server and the guard, not the correctness of a filing's own accounting. A validated filing is a filing that parsed and passed its profile, not a filing that is true.
Links
Defects in this package are issues in its own repository.
Author approval — 2026-08-23, hash 984b393d