coreprocess/loupe-mcp

Loupe is an MCP server that reads documents for AI agents. It turns PDFs, scans, photos and Office files into text, at one of two quality levels:
| Quality | How | Result |
| fast | Azure Document Intelligence, layout model | Markdown per page |
| accurate | Document Intelligence (high-resolution OCR), the PDF's text layer and form fields, and an image of the page, reconciled per page by a vision model | HTML per page; photos and drawings described, checkboxes, handwriting and strike-through marked |
Accepted inputs: PDF; JPEG, PNG, BMP, TIFF (multi-page), HEIC/HEIF; DOCX, DOCM, XLSX, PPTX; HTML. Types are detected by content, never by name.
Agents upload files from their sandbox with curl to a signed URL, submit them as one batch job, and read the text page by page in context or download it. Jobs run independently of the MCP connection, report progress per document, and continue on another replica if one restarts. One Loupe deployment serves many projects.
The full design is in docs/CONCEPT.md.
## Tools
| Tool | Purpose |
| createupload | Creates an upload and returns a signed URL; PUT each file to |
| submit | Starts a job over an upload's files at quality fast or accurate, optionally with a language hint and a page selection |
| getjob | Status, progress per document, page methods, and one manifest URL for downloads |
| readresult | Whole pages of one document's transcript, as many as fit into a window |
| canceljob | Stops a job; documents already read stay readable |
A typical session:
text
createupload() → u8sLx2…, uploadUrl
submit("u8sLx2…", "accurate", language: "de") → j4fKq9…, 120 documents
getjob("j4fKq9…", wait: 10) → running, 37 of 120 succeeded
readresult("j4fKq9…", "contract.pdf") → pages 1–4
bash
U=" "; for f in scans/; do curl -fsS -T "$f" "$U"; done
M=" "; B="${M%/manifest.json}"
curl -fsS "$M" | jq -r '.documents[] | select(.status == "succeeded") | .path' \
| xargs -P4 -I{} curl -fsS --create-dirs -o {} "$B/{}"
## Run locally (stdio)
Requires Node.js 24, pnpm, and an Azure Document Intelligence resource plus an Azure OpenAI deployment of a vision model.
bash
pnpm install
cp .env.example .env.loupe # add your endpoints and keys
node src/index.ts --env-file .env.loupe
Register it with Claude Code:
bash
claude mcp add loupe -- node /path/to/loupe-mcp/src/index.ts --env-file /path/to/.env.loupe
In stdio mode, the store is ./.loupe/store, and upload and download URLs point to a small HTTP endpoint on 127.0.0.1 that the server starts alongside.
With Docker (the published image runs the HTTP transport by default):
bash
docker run -i --rm --env-file .env.loupe \