StayPut

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.

Tools

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 mcpnpm installnpm test   # builds dist/index.js and runs the end-to-end tests

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.