gotenberg-mcp by alexandreshah - MCP Server

Gotenberg MCP Server

A Model Context Protocol (MCP) server that provides tools for document conversion using Gotenberg.

Features

This MCP server exposes Gotenberg's document conversion capabilities as MCP tools:

convert_url_to_pdf - Convert web pages to PDF
convert_html_to_pdf - Convert HTML content to PDF with optional headers/footers
convert_markdown_to_pdf - Convert Markdown to PDF with custom styling
convert_office_to_pdf - Convert Office documents (Word, Excel, PowerPoint) to PDF
merge_pdfs - Merge multiple PDF files into one
screenshot_url - Take screenshots of web pages

Prerequisites

Gotenberg Server: You need a running Gotenberg instance
```
docker run --rm -p 3333:3000 gotenberg/gotenberg:8
```
Python 3.10+: Required for running the MCP server

Installation

Install dependencies:
```
pip install -r requirements.txt
```
Make the server executable:
```
chmod +x server.py
```

Configuration

The server is configured to connect to Gotenberg at http://localhost:3333 by default. If your Gotenberg instance is running on a different host/port, edit the GOTENBERG_URL variable in server.py.

Usage with Claude Desktop

Add this to your Claude Desktop configuration file:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gotenberg": {
      "command": "python3",
      "args": ["/absolute/path/to/gotenberg-mcp/server.py"]
    }
  }
}

Note: Replace /absolute/path/to/gotenberg-mcp/ with the actual path where you cloned this repository. If using a virtual environment, use the full path to that Python executable.

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "gotenberg": {
      "command": "python",
      "args": ["C:\\absolute\\path\\to\\gotenberg-mcp\\server.py"]
    }
  }
}

Example Usage

Once configured, you can use these tools in Claude:

Convert a webpage to PDF:

Convert https://example.com to a PDF and save it as example.pdf

Convert HTML to PDF:

Convert this HTML to PDF: <html><body><h1>Hello World</h1></body></html>

Merge PDFs:

Merge document1.pdf and document2.pdf into combined.pdf

Convert Office documents:
```
Convert my report.docx to PDF
```

Tools Reference

convert_url_to_pdf

url (required): URL of the webpage to convert
output_path (required): Where to save the PDF
landscape (optional): Use landscape orientation
page_ranges (optional): Specific pages to print (e.g., "1-3, 5")
scale (optional): Scale of the webpage (0.1 to 2.0)

convert_html_to_pdf

html_content (required): HTML content to convert
output_path (required): Where to save the PDF
landscape (optional): Use landscape orientation
header_html (optional): HTML for page header
footer_html (optional): HTML for page footer

convert_markdown_to_pdf

markdown_content (required): Markdown content to convert
output_path (required): Where to save the PDF
landscape (optional): Use landscape orientation
css_content (optional): Custom CSS styling

convert_office_to_pdf

file_path (required): Path to Office document
output_path (required): Where to save the PDF
merge (optional): Merge multiple documents into one PDF
pdfa (optional): Convert to PDF/A format (e.g., "PDF/A-1b")

merge_pdfs

pdf_paths (required): List of PDF files to merge
output_path (required): Where to save the merged PDF

screenshot_url

url (required): URL to screenshot
output_path (required): Where to save the screenshot
format (optional): Image format (png, jpeg, webp)
quality (optional): Image quality (0-100, for JPEG/WebP)

Troubleshooting

Connection errors: Ensure Gotenberg is running and accessible at the configured URL
Permission errors: Make sure the output directories exist and are writable
Timeout errors: Large documents may take longer to convert; the timeouts are set to 60-120 seconds

Development

To modify the server:

Edit server.py to add new tools or modify existing ones
Restart Claude Desktop to reload the MCP server
Check Claude Desktop logs for debugging information

License

MIT License - See Gotenberg's license for the underlying conversion tools.