Skip to main content
Glama
gurupdf-mcp
by GuruPDF

GuruPDF MCP — convert PDFs & 100+ file formats from your AI agent

npm version License: MIT gurupdf-mcp MCP server

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:

  1. Sign up at gurupdf.com.

  2. Open Profile → API tokens and create a token.

  3. Add the server to your agent with that key (configs below). No install step — npx fetches 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_file

Convert/process a local file (or URL). Give it an input and a target format (pdf, png, docx…) or a tool slug (compress-pdf, merge-pdf…). Saves the result to disk.

get_status

Check a conversion job by id and download the result when ready (for long jobs like video).

list_conversions

List supported conversions/tools, optionally filtered by an input format.

check_credits

Show remaining credits and how to get more.

Examples

"Compress ~/Documents/report.pdf." → convert_file(input: "~/Documents/report.pdf", to: "compress-pdf")

"Convert invoice.docx to PDF." → convert_file(input: "invoice.docx", to: "pdf")

"Merge a.pdf and b.pdf into 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

GURUPDF_API_KEY

—

Required. Your API token from Profile → API tokens.

GURUPDF_API_URL

https://gurupdf.com/api/v1

Override only for self-hosted / staging.

gurupdf-mcp MCP server

License

MIT

Available Tools

4 tools
check_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

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: credits, conversion initiation, job status checking, and listing supported formats. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to understand.

    Tool Count5/5

    Four tools is appropriate for a PDF conversion service, covering the essential operations without being excessive or insufficient.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to perform 13 PDF operations (merge, split, compress, watermark, encrypt, and more) on local files via MCP.
      3
      -
    • A
      license
      A
      quality
      B
      maintenance
      Convert 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.
      3
      45 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      18
      50 PyPI
      MIT