# GuruPDF/gurupdf-mcp [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/GuruPDF/gurupdf-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 424  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gurupdf-gurupdf-mcp

## Description
Convert, compress, merge, split, and OCR PDFs, plus convert between 100+ file formats (Word, Excel, PowerPoint, images, ebooks, video) from any AI agent. Backed by the GuruPDF API; free tier with daily credits, zero-config via npx gurupdf-mcp.

## Tools
Capabilities this server exposes over MCP:

- **convert_file** — 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.
- **get_status** — Check a GuruPDF conversion job by its id (uuid). If it's finished, downloads the result to disk.
- **list_conversions** — List the conversions and tools GuruPDF supports, optionally filtered by an input file format.
- **check_credits** — Show how many GuruPDF credits the user has left, and how to get more.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "gurupdf-mcp": {
    "command": "npx",
    "args": ["-y","gurupdf-mcp"],
    "env": {
      "GURUPDF_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `GURUPDF_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/gurupdf-gurupdf-mcp/readme_