gurupdf-mcp
OfficialConvert and process PDFs and 100+ file formats from an AI agent using GuruPDF’s API.
convert_file: Convert local files or URLs to formats like PDF, DOCX, PNG, etc., or run PDF tools such as compress, merge, split, rotate, protect, watermark, and OCR; saves results to disk.get_status: Check a conversion job by UUID and download the finished result.list_conversions: List supported conversions/tools, optionally filtered by input format.check_credits: Show remaining GuruPDF credits and how to get more.Works with local file paths and URLs, so no manual upload/download is needed; requires
GURUPDF_API_KEY.
Enables Windsurf (by Codeium) to convert and process PDFs and other file formats, including OCR, compression, merging, splitting, rotation, protection, and watermarking.
GuruPDF MCP — convert PDFs & 100+ file formats from your AI agent
A free Model Context Protocol (MCP) server that lets Claude, Cursor, VS Code, Windsurf and other AI agents convert, compress, merge, split and edit PDFs — and convert between 100+ file formats (Word, Excel, PowerPoint, JPG, PNG, HEIC, ebooks, and more), right on your own machine. Powered by GuruPDF.
Languages: English · Español · Français · Deutsch · 中文 · Русский · Українська · Polski · Nederlands · Türkçe · Čeština · Ελληνικά · العربية
Ask your assistant: "compress this PDF", "turn invoice.docx into a PDF", or "merge these three files" — and it converts the files right on your machine.
🗂️ 127 tools — PDF ⇄ Word/Excel/PowerPoint, images, ebooks, OCR, compress, merge, split, rotate, protect, watermark, and more.
💻 Works on your local files — reads and writes files on disk, no manual upload/download.
🆓 Free to start — every account gets daily credits. No credit card required.
Install
You need Node.js 18+ and a free GuruPDF API key:
Sign up at gurupdf.com.
Open Profile → API tokens and create a token.
Add the server to your agent with that key (configs below). No install step —
npxfetches it on first run.
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"gurupdf": {
"command": "npx",
"args": ["-y", "gurupdf-mcp"],
"env": { "GURUPDF_API_KEY": "your_token_here" }
}
}
}Cursor
~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"gurupdf": {
"command": "npx",
"args": ["-y", "gurupdf-mcp"],
"env": { "GURUPDF_API_KEY": "your_token_here" }
}
}
}VS Code
.vscode/mcp.json:
{
"servers": {
"gurupdf": {
"command": "npx",
"args": ["-y", "gurupdf-mcp"],
"env": { "GURUPDF_API_KEY": "your_token_here" }
}
}
}Windsurf
~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"gurupdf": {
"command": "npx",
"args": ["-y", "gurupdf-mcp"],
"env": { "GURUPDF_API_KEY": "your_token_here" }
}
}
}Related MCP server: agentmd-mcp
Tools
Tool | What it does |
| Convert/process a local file (or URL). Give it an input and a target format ( |
| Check a conversion job by id and download the result when ready (for long jobs like video). |
| List supported conversions/tools, optionally filtered by an input format. |
| Show remaining credits and how to get more. |
Examples
"Compress
~/Documents/report.pdf." →convert_file(input: "~/Documents/report.pdf", to: "compress-pdf")
"Convert
invoice.docxto PDF." →convert_file(input: "invoice.docx", to: "pdf")
"Merge
a.pdfandb.pdfinto one." →convert_file(input: ["a.pdf", "b.pdf"], to: "merge-pdf")
"Password-protect this PDF with
hunter2." →convert_file(input: "secret.pdf", to: "protect-pdf", options: { password: "hunter2" })
"Save this web page as a PDF: https://example.com" →
convert_file(input: "https://example.com", to: "url-to-pdf")
Free tier & credits
Each tool costs a few credits. Free accounts get daily credits (refreshed every day) and 2 conversions/minute, 10/day. When you run out, the assistant will tell you — you can wait for the daily refresh or top up / upgrade. Conversions run on GuruPDF's servers; files are deleted automatically within an hour.
Configuration
Env var | Default | Notes |
| — | Required. Your API token from Profile → API tokens. |
|
| Override only for self-hosted / staging. |
Links
Glama: gurupdf-mcp on Glama
Landing page: gurupdf.com/mcp
Guide: Convert files in Claude & Cursor with the GuruPDF MCP
Website: gurupdf.com
API docs: gurupdf.com/api/docs
Pricing: gurupdf.com/pricing
License
MIT
Available Tools
4 toolscheck_creditsA
Show how many GuruPDF credits the user has left, and how to get more.
Inputs: no named parameters.
convert_fileA
Convert or process a local file (or URL) with GuruPDF. Convert between 100+ formats (PDF ⇄ Word/Excel/PowerPoint, images, ebooks, etc.) or run a PDF tool (compress, merge, split, rotate, protect, watermark, OCR…). Saves the result next to the input and returns the path.
Inputs: to (required), input (required), wait, options, +1 more.
get_statusA
Check a GuruPDF conversion job by its id (uuid). If it's finished, downloads the result to disk.
Inputs: uuid (required), output_dir.
list_conversionsA
List the conversions and tools GuruPDF supports, optionally filtered by an input file format.
Inputs: from_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: credits, conversion initiation, job status checking, and listing supported formats. No overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to understand.
Four tools is appropriate for a PDF conversion service, covering the essential operations without being excessive or insufficient.
The tool set covers core operations: checking credits, initiating conversions, checking status, and listing formats. A minor gap is the lack of a cancel job tool, but the set is largely complete for typical workflows.
Maintenance
Related MCP Connectors
13 stateless PDF tools for AI agents: merge, split, rotate, compress, watermark, redact, flatten, repair, add page numbers and fill PDF forms. Files are processed in memory and nothing is stored. Part of FreeDailyPro's 211+ MCP tools; trial key with 20,000 calls/month at freedailypro.com/developers.
PDF and image tools for AI agents: compress, merge, split, OCR, sign. Runs locally, never uploads.
PDF tools for agents: compress to a size, Arabic + English OCR, Office conversion, JSON extraction.
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to perform 13 PDF operations (merge, split, compress, watermark, encrypt, and more) on local files via MCP.3-
- AlicenseAqualityBmaintenanceConvert PDF, DOCX, HTML, and URLs into clean, LLM-ready markdown with tables preserved and boilerplate stripped, through three MCP tools (URL, local file, or raw bytes). Hosted API with no local dependencies; 50 free conversions with a self-serve key, then $0.002 per call.345 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to edit text inside real PDF files in place while preserving fonts and layout, with a before/after preview. Also supports compressing, merging, splitting, converting, translating, generating and querying PDFs through a hosted remote MCP endpoint.MIT
- AlicenseBqualityCmaintenanceEnables AI agents to convert documents, images, and data files across 50+ format pairs and to run PDF/image operations such as merge, split, compress, rotate, protect, unlock, extract text, and resize or compress images. Files are passed URL-in and returned URL-out (or saved locally in stdio mode), with tools for checking credits and generating Stripe checkout or billing-portal links.1850 PyPIMIT