evidence-ledger-mcp

Under active development. Both the schema and the server may change in breaking ways between versions until v1.0. Pin the version you use.

An MCP server through which agents keep an evidence ledger for the citations in a work: for each claim, the source that backs it, where in the source, a short quote and why the citation is needed. Co-authors, scripts or a second model can then check every citation against its source.

It is built for academics: authors and co-authors who write with LLMs and want every citation to stay checkable. The ledger format is an open schema, so a graduate school could require it for theses, and a journal could adopt it for submissions or build its own standard on it.

Supported schema: v0.4.0 · standalone schema repository (how schema versions are pinned).

The MCP server and its associated documentation use the MIT licence. The bundled schema uses CC BY 4.0, with attribution to Matthias Kloft. These licences do not cover ledger contents or third-party source material.

The evidence ledger schema

Every ledger this server writes follows the evidence ledger schema (JSON Schema, draft 2020-12), currently v0.4.0. The schema is the contract: any tool, script or person can read, validate and check a ledger with it, with or without this server. Its README documents the purpose, the file shapes, every record field, quote hashing, a minimal example and the sources the fields draw on. The server bundles a pinned copy in schema/ and reports the supported version through schema_info.

A ledger is a header (schema_version, work and optional notes) followed by records. Each record links one claim in the work to one source passage:

A minimal record, as passed to add_record (the server adds the IDs, hash and date):

{
  "claim": "Retrieval practice improves long-term retention.",
  "claim_type": "empirical",
  "contestable": true,
  "anchor": {"exact": "testing improves later recall"},
  "key": "example2020",
  "doi": "10.1234/example",
  "locator": {"page": 12},
  "quote": "participants who were tested recalled more after one week",
  "relation": "supports",
  "justification": "Direct experimental evidence for the claim.",
  "retrieved_via": "pdf"
}

with provenance such as {"by_type": "agent", "by": "Claude Code", "model": "claude-opus-5-5"}. Ledgers are stored as JSON Lines; see docs/schema.md.

What it does

• Write ledgers safely. Records are validated against the schema before they are appended. The server assigns record and claim IDs, computes quote hashes and dates the provenance instead of leaving them to the agent.
• Keep the history. The server never deletes records; a withdrawn record keeps its reason.
• Find gaps. Search by claim, source key or text, and list contestable claims still missing evidence.
• Share without leaking sources. Exports and summaries come at three levels: full (private), masked (short excerpts) and locator (no quoted text). A publication check refuses to write a file that carries more source text than its level allows.
• Read it as a report. A standalone HTML summary, grouped by claim, prints to PDF from a browser.
• See the evidence in the work. The claims are marked in the work's own HTML and linked to their evidence, as end notes or in a side panel.
• Check it against the work and its sources. Find anchors that no longer appear in the work, records assessed against another revision, quotes that the source text no longer holds, and citation keys missing from the bibliography. Source text can be passed in, or the server fetches it from public URLs (web pages, plain text and PDFs with a text layer).

Installation

Requires Python 3.11 or newer. The server speaks MCP over stdio. With uv, run the released version from PyPI:

uvx --from evidence-ledger-mcp==0.3.1 evidence-ledger-mcp

For example, to add it to Claude Code:

claude mcp add evidence-ledger -- uvx --from evidence-ledger-mcp==0.3.1 evidence-ledger-mcp

Other MCP clients take the same command and arguments. To run a source checkout instead, use uv sync, then configure the client to run uv with arguments run, --directory, the absolute path to the checkout, and evidence-ledger-mcp.

Pass absolute ledger paths to tools; relative paths resolve against the server's working directory.

Tools

Typical workflow

1. create_ledger once per work, next to the manuscript or code.
2. add_record whenever a source is cited, with the claim, its anchor, the source key, locator, quote, relation and justification. The server fills in IDs, the quote hash and the provenance date.
3. find_records with missing_evidence and validate_ledger before submission, to find claims still lacking evidence.
4. check_ledger with the rendered work, its bibliography and the sources (as text or public URLs), to catch anchors, keys and quotes that no longer match.
5. export_ledger, summarize_ledger or embed_ledger at masked or locator level to share the ledger with co-authors, reviewers or a journal.

The tool reference covers export levels, masking, embedding and every check in detail.