MCP_Documents

A self-hosted MCP server for reading, extracting from and manipulating documents — PDF first, but not PDF only.

The seventh repo in the MCP_* fleet, and the one that closes the research leg of the research → analytics → reporting path the fleet exists to serve.

Release v0.2.0 — the second tagged release. All 13 tools are implemented and deployed; CI is green on Ubuntu, macOS and Windows. Source only: no wheel and no container image are published, so build the image yourself from the Dockerfile here. The documents in docs/ remain the contract the implementation satisfies, and CLAUDE.md is the rulebook for anyone changing it.

Why this exists

The commercial PDF sites are upload-first. The documents people actually run through them are contracts, invoices, payslips, medical and legal records.

This does the same work and nothing leaves the machine. No GPU, no cloud API, no model weights, no subscription — and it works offline.

Related MCP server: Knowledge Assistant MCP

What it does

Extraction from documents too large to read. A 500-page PDF is roughly 250,000 tokens; the agent driving it has about 10,000. So the server does not return documents, it makes them addressable:

probe    what is this — pages, scanned or digital, where the structure is
find     WHERE something is — locations and counts, never the content
extract  one region you chose, cleaned, with a note on how it was obtained

That path is what lets an agent answer a question about a 500-page bundle inside a small context. With a regex and named groups, find over 300 pages returns rows rather than prose — which is what the sibling data server loads.

Manipulation, the operations a PDF site offers, done locally: assemble (merge / split / reorder / rotate in one grammar), convert, compress, repair, OCR, protect, redact.

Any document, not just PDF. One reader per format normalising into a single internal model, so every tool works the same on PDF, HTML, .docx, .xlsx, .pptx, .eml, .epub, .xbrl, markdown and plain text. With URL fetching enabled, every path argument also accepts a link — the same call, whether the HTML came from disk or the web.

Bundles open too. A .zip reads as its manifest, and a member is read by naming it — probe("filing.zip::instance.xbrl") — so a filing that arrives as an archive does not have to be unpacked by hand first. A member this server does not read, or one wanted as a file, is saved as it is with convert(source="filing.zip::data.csv", to="file"), after the same size guards. Reading a member writes nothing where outputs go: it is unpacked into a cache private to the server (DOCS_MEMBER_CACHE, default under the system temp folder).

XBRL figures come back native. Every other format's numbers are recovered from layout and carry a confidence to match; an XBRL instance states its facts in machine-readable fields, and the response says so. Values are reported exactly as filed and never rescaled.

The 13 tools

docs-read   probe · outline · find · extract · extract_tables · read_page · to_markdown
docs-edit   assemble · convert · optimize · ocr · protect · redact

Thirteen, not the twenty-five a PDF website shows, because that number is a property of user interfaces — a button cannot take an argument and an agent's verb can. assemble alone covers merge, split, extract pages, remove pages, organise and rotate.

One endpoint, two tools

/mcp serves all thirteen as two domain tools, docs_read and docs_edit, each taking an action (one of the verbs above, by its own name) and an args object whose every property says which actions take it:

{"action": "outline", "args": {"source": "report.pdf"}}

Each action runs the tier's own tool, so validation and answers are identical. An action asked of the wrong tool is pointed at the right one; an argument it does not take is refused by name. /read/mcp and /edit/mcp keep serving.

Documentation

Two things worth knowing before you use it

Reconstruction announces itself. A PDF is glyphs at coordinates — paragraphs, tables, reading order and headings are all inferred. Every extraction carries a basis field saying how it was obtained: a table found from ruling lines and one guessed from column gaps do not get the same confidence, and a page that is an un-OCR'd scan says so instead of returning nothing.

PDF → Word/PowerPoint is reconstruction, not conversion. The commercial sites use commercial engines and there is no CPU-only open-source path to that quality. This ships it, labels it, and tells you when a document is a poor candidate.

Install

Requires Python 3.14 and uv. Set MCP_CONSTRAINED_MODE=1 on small hardware to tighten every budget. A caller's regular expression, in find and in redact, runs in a worker that is stopped after DOCS_REGEX_SECONDS of matching (10, 5 constrained) and refused by name.

Local, as a stdio server

uv sync
uv run python servers/docs_read/server.py      # 7 read tools
uv run python servers/docs_edit/server.py      # 6 edit tools

Two entries in your client's mcp.json, one per tier. Everything runs on the CPU with no network; convert(to='pdf') needs LibreOffice and ocr() needs Tesseract, and both say so by name when they are missing rather than failing inside a subprocess.

Docker, as a remote endpoint

One container, both tiers on one port, so the PDF stack loads once:

cp tokens.example.json tokens.json          # or use DOCS_API_KEY
mkdir -p oauth-state shared-files && sudo chown -R 999:999 oauth-state shared-files tokens.json
docker compose up -d --build

curl http://localhost:8850/health            # aggregate
curl http://localhost:8850/read/health       # per tier
# connect /mcp for the two domain tools, or /read/mcp and /edit/mcp for the tiers

The image carries LibreOffice and Tesseract. It does not carry Ghostscript — that is a licence decision, not an omission, and optimize() reports the capability it therefore lacks (see docs/DECISIONS.md §11). Build with --build-arg INSTALL_GHOSTSCRIPT=1 if you accept AGPL for your own deployment.

Mounts are /read/mcp and /edit/mcp. Auth is bearer-token, by precedence: DOCS_TOKENS_FILE > DOCS_TOKENS > DOCS_API_KEY > open. Open mode is for localhost only — a reachable deployment with no token set has no auth at all. Set DOCS_PUBLIC_URL to the public origin, or OAuth discovery falls back to the internal bind address and no remote client can complete it.

To give a caller a link rather than a path inside the container, point MCP_SHARED_DIR at a directory your file server serves and set MCP_PUBLIC_BASE_URL to its URL; every produced file then comes back with a public_url. MCP_FETCH_URLS=1 additionally lets any source argument be an http(s) link — off by default, and private, loopback and cloud-metadata addresses are refused even when it is on. A Google Drive, Docs, Dropbox, GitHub or GitLab share link is read as the file it points to, and a web page served where a file was asked for (a link that is not public answers with a sign-in page) is refused, not parsed. A path from the caller's side -- a chat's sandbox such as /mnt/user-data/… -- is refused by name, with the ways to bring the file here.

Where a source goes, a file's bytes may go instead: data:application/pdf;name=report.pdf;base64,<bytes> is saved to MCP_OUTPUT_DIR/inbox/report.pdf before the tool runs. It is for a caller whose file sits in its own sandbox (a claude.ai upload) with no link to give, capped at MCP_MAX_INLINE_MB (default 10); the same bytes sent twice are one file, and a taken name is never overwritten. A bigger file goes in parts: add part=2/5;sha256=<of the whole file> to each. The tool answers tool_ran: false with the parts still missing until the last lands, then runs on the joined, checked file (MCP_MAX_UPLOAD_MB, default 100; an upload left unfinished for an hour is dropped).

Upload URLs are off by default. With MCP_UPLOAD_URLS=1 and MCP_UPLOAD_BASE_URL (this server's public origin), the refusal for a path on the caller's side carries a URL minted for that file: curl -T <file> '<url>' from the sandbox writes it to MCP_OUTPUT_DIR/inbox/, and the answer is the path to pass. The bytes never pass through the model. A URL writes one file, once, within 15 minutes, up to MCP_MAX_UPLOAD_MB, under the name fixed when it was minted; a forged, expired or spent one writes nothing. The route takes no API key -- its signed token (MCP_UPLOAD_SECRET, else a key made per process) is the credential -- so turning it on is the operator's decision.

Checking a deployment

uv run python -m pytest tests/ -q                     # 497 offline tests
DOMAIN=http://localhost:8850 ./remote_smoke_test.sh   # all 13 tools over HTTP

The smoke test is the only thing that exercises LibreOffice and Tesseract, and it is worth more than its size suggests: it found six defects the whole offline suite did not, because it is the only check that hands these tools a document real software produced. DOMAIN has no default on purpose — no hostname appears anywhere in this repo.