Convert Files in Claude and Cursor with the GuruPDF MCP

Your coding agent can scaffold an app, untangle a stack trace, and argue with you about tabs versus spaces. Hand it a PDF and ask for an editable Word doc, though, and it stalls. Files live on your disk; the model lives in the chat. Nothing connects the two.

That gap is the whole reason we built the GuruPDF MCP — a small server that gives Claude, Cursor, and any other MCP client a way to actually convert files. Put a path in your prompt, say what you want, and the converted file lands back on your disk a moment later. No upload screen, no "download it, then re-upload it somewhere else." Just "convert ~/contracts/lease.pdf to Word."

What a file-conversion MCP actually is

MCP — the Model Context Protocol — is the plug that lets an AI agent use tools outside its own head. A server exposes a few actions; the agent calls them when your prompt needs them. There are MCP servers for databases, browsers, GitHub.

There wasn't a good one for files. So a PDF MCP — really a file-conversion MCP, since it reaches well past PDF — is just a server that takes a file in one format and hands back another. PDF to Word. A folder of images to one PDF. A scanned page to searchable text. The agent does the asking; GuruPDF does the converting.

Under the hood it's the same engine behind gurupdf.com: 126 tools, 100+ formats, now reachable from inside your editor.

Set it up in about two minutes

You need two things: Node (for npx) and a free GuruPDF API key. Grab a key at gurupdf.com/profile — free accounts come with daily credits, so you can start converting straight away.

The server installs and runs itself through npx; there's nothing to clone:

bash

npx gurupdf-mcp

You won't run that by hand, though — you point your MCP client at it. For Cursor, Claude Desktop, VS Code, or Windsurf, drop this into your MCP config:

json

{
  "mcpServers": {
    "gurupdf": {
      "command": "npx",
      "args": ["-y", "gurupdf-mcp"],
      "env": { "GURUPDF_API_KEY": "your-token-here" }
    }
  }
}

Restart the client and your agent quietly gains four tools: convert a file, check a job, list what's supported, and check your credit balance. That's the whole setup.

What you can actually do with it

This is the fun part. Once it's wired up, these are real prompts that just work:

"Convert ~/Downloads/invoice.pdf to Word so I can edit the totals." — an editable .docx appears next to the original.
"Turn every screenshot in ~/shots into one PDF." — images merged, in order, into a single file.
"This scan is just an image. OCR it and give me the text." — real text pulled back out of the pixels.
"Compress report.pdf, it's 40 MB and I need to email it." — a smaller file that's still readable.
"Make a PDF of https://example.com/pricing." — the live page, rendered to PDF.

You never memorize tool names or formats. Say the goal in plain language and the server picks which of the 126 tools fits, runs it, and writes the result to disk. Merge, split, rotate, password-protect, watermark, Excel ↔ PDF, HEIC → JPG — they're all in there.

It talks back when something's off

Most converters fail with a cryptic code. This one is built to explain itself through your agent, because the agent is the thing reading the reply.

Run low on the free tier and you won't get a bare 402. You get a sentence your assistant passes along: you've hit the free limit (2 conversions a minute, 10 a day), it resets tomorrow, and here's a link if you'd rather not wait. Hand a tool the wrong format, or a file that's too big, and it tells you exactly that — in words, not an error number. You never have to leave the conversation to work out what happened.

That "explain it through the agent" idea is also why we fuss over the wording. An error message a human never reads still has to make sense to the model relaying it.

What's under the hood

126 tools, 100+ formats. PDF, Word, Excel, PowerPoint, images, e-books, even video — the same engine as the website.
A real free tier. Every account gets daily credits. Paid plans and credit bundles exist for heavier use, and your agent points you to them when it actually makes sense, not before.
Files don't linger. Everything moves over HTTPS and is deleted within an hour. The MCP writes the result to your disk; the copy on our side is gone shortly after.
Open source. The server is MIT-licensed, published on npm and listed in the official MCP registry, so you can read every line before you run it.