Gurupdf MCP

What GuruPDF/gurupdf-mcp MCP server does

GuruPDF/gurupdf-mcp MCP server connects an MCP-compatible AI client to the GuruPDF API for document conversion and PDF processing. It can convert among PDF, Word, Excel, PowerPoint, image, ebook, and other formats, with support for more than 100 format combinations. PDF-focused operations include compression, merging, splitting, rotation, password protection, watermarking, and OCR.

The server works with files on the machine running the AI client. It can also accept a URL for supported operations, such as creating a PDF from a web page. Completed output is written to disk and the resulting path is returned to the agent.

How it works

The central convert_file tool receives a local path, a URL, or a list of input files. The caller supplies either a target format such as pdf, png, or docx, or a GuruPDF operation slug such as compress-pdf or merge-pdf. For multi-file workflows, the input can contain multiple paths.

Some conversions may run as asynchronous jobs. get_status checks a job by its UUID and downloads the output when processing is complete, which is useful for longer-running work such as video conversion. list_conversions reports available conversions and processing tools, with optional filtering by input format. check_credits reports the remaining account credits and explains how to obtain more.

GuruPDF/gurupdf-mcp MCP server sends conversions to GuruPDF’s servers rather than processing every operation locally. The README states that uploaded files are automatically deleted within one hour.

Setup and configuration

Node.js 18 or newer is required. Create a free GuruPDF account, generate an API token under the profile’s API tokens page, and provide it as GURUPDF_API_KEY. The package can be launched with npx -y gurupdf-mcp, so a separate local installation step is not required.

Claude Desktop, Cursor, VS Code, and Windsurf configurations use the same command and environment variable. This listing specifically identifies Claude Desktop, Cursor, and Windsurf as compatible clients. The optional GURUPDF_API_URL variable defaults to https://gurupdf.com/api/v1 and can be changed for self-hosted or staging deployments.

Tools and capabilities

• convert_file: Convert a file between supported formats or run a PDF operation; writes the result to disk.
• get_status: Check an asynchronous conversion and download its completed result.
• list_conversions: Discover supported conversions and tools, optionally by input format.
• check_credits: Display the account’s remaining GuruPDF credits.
• Handle PDF conversion, compression, merging, splitting, rotation, protection, watermarking, and OCR.
• Convert among PDF, office documents, images, ebooks, video, and other supported formats.

GuruPDF/gurupdf-mcp MCP server uses account credits. Free accounts receive daily credits, with the README also documenting a limit of two conversions per minute and ten per day. Additional capacity is available through GuruPDF’s top-up or upgrade options.

Limitations and notes

An API key is required, even though the service has a free tier. Conversion work is performed on GuruPDF’s servers, so this tool may not fit workflows that require all file processing to remain offline. The documented free-tier limits and automatic deletion window should be considered when planning batch jobs or handling sensitive documents.

The configured input and output paths must be accessible to the local AI client process. For long-running jobs, an agent needs to retain the returned job ID and call get_status to retrieve the result.