Stayput MCP server
Local PDF and photo tools for Claude, Cursor, VS Code and any other app that speaks the Model Context Protocol. Ask your assistant to merge PDFs, pull out pages, or remove the GPS location from a photo, and it does the work on your own machine.
It runs the same code as stayput.dev, the browser version. Your files are read from disk and written back to disk; nothing is uploaded, and the server makes no network requests. It is free and open source (MIT), with no account and no API key.
| Tool | What it does |
|---|
merge_pdfs | Combine PDFs into one, in the order given |
extract_pdf_pages | Keep only some pages, reorder them ("3,1,2") or drop pages |
split_pdf | Split into one file per page, or every N pages |
rotate_pdf | Rotate all pages or chosen pages by 90, 180 or 270 degrees |
number_pdf_pages | Stamp page numbers, e.g. "Page {n} of {total}" |
pdf_info | Page count, page sizes and title |
images_to_pdf | JPG and PNG images into one PDF, one per page, no re-compression |
inspect_image_metadata | Show GPS location, camera, capture time and other hidden metadata in a photo |
strip_image_metadata | Write a copy of a JPG, PNG or WebP with EXIF, GPS, XMP and comments removed, without re-encoding |
Every tool writes a new file and returns its path. Input files are never modified, and an existing file is never overwritten (you get file-1.pdf instead). Encrypted PDFs (bank statements, forms with printing restrictions) are decrypted locally with qpdf; for PDFs that need a password to open, the assistant passes it in the password argument.
Install
Requires Node.js 20 or newer.
Claude Code
claude mcp add stayput -- npx -y stayput-mcp
Claude Desktop, Cursor, Windsurf and other JSON configs (claude_desktop_config.json, .cursor/mcp.json, ...)
{
"mcpServers": {
"stayput": {
"command": "npx",
"args": ["-y", "stayput-mcp"]
}
}
}
VS Code
code --add-mcp '{"name":"stayput","command":"npx","args":["-y","stayput-mcp"]}'
Then ask things like:
- "Merge invoice-march.pdf and invoice-april.pdf in ~/Downloads"
- "Take pages 2 to 5 out of contract.pdf"
- "Does IMG_2041.jpg have a location in it? If so, make a copy without it"
- "Number the pages of thesis.pdf, starting on page 3"
Relative paths are resolved from the folder the server was started in, so absolute paths or ~/... are the safest thing to give it.
Not covered here
HEIC, WebP and AVIF conversion, compression, PDF to image and PDF signing need a browser engine. They are on stayput.dev, which works the same way: in your browser, nothing uploaded.
Development
cd mcp
npm install
npm test
The tests use the site's fixtures; generate them first from the repository root with python3 tests/fixtures/make-fixtures.py && node tests/fixtures/make-pdf.mjs (needs Pillow and pillow-heif).
The server imports the PDF and metadata code from ../src/lib and bundles it with esbuild (build.mjs). Two browser-only modules are swapped at build time: src/unlock.ts loads qpdf from node_modules instead of a <script> tag, and src/no-canvas.ts stands in for the canvas helpers that only PDF compression uses.