Conversion Service MCP Server

An MCP server for the PDF Tools Conversion Service Simple API v6.9.1, built from the official openapi.yaml spec.

Tools

Tool	Endpoint	Description
convert_to_pdfa2	archive-pdfa2-default	Convert to PDF/A-2 (recommended archival)
convert_to_pdfa3	archive-pdfa3-default	Convert to PDF/A-3 (e-invoices)
convert_to_pdf	convert-to-pdf	Convert any supported format to standard PDF
merge_to_pdf	dossier-default	Merge multiple documents into one PDF
convert_to_pdfa2_print	archive-pdfa2-print-optimization	PDF/A-2 optimized for printing
convert_to_pdfa2_web	archive-pdfa2-web-optimization	PDF/A-2 optimized for web
convert_to_pdfa2_email	archive-pdfa2-email-optimization	PDF/A-2 optimized for email
repair_pdf	repair-pdf	Convert to PDF, validate and repair
convert_large_file	http.input/*	Plain HTTP multipart for files >100 MB
list_profiles	--	List all available profiles and endpoints

Dependencies

pip install mcp httpx

Local Conversion Service Setup

The MCP server connects to a running instance of the PDF Tools Conversion Service. The easiest way to run it locally is via Docker.

Prerequisites

• Docker Desktop installed and running
• The eso-consrv repo cloned locally

Port conflicts (Windows only)

If you have the PDF Tools Windows services installed, they bind to the same ports as the Docker containers. Stop them first in an elevated PowerShell:

net stop "Pdftools Licensing Gateway Service"
net stop "Pdftools Conversion Service Connections"

To prevent them from auto-starting on reboot (run once):

Set-Service "LicensingGatewayService" -StartupType Manual
Set-Service "ConversionServiceConnectionService" -StartupType Manual
Set-Service "ConversionService" -StartupType Manual

Start the containers

From the eso-consrv repo root:

docker compose --env-file docker-compose.env up -d

Ports

Service	Port	Purpose
license-gateway	9999	License management
conversion-service	13033	Advanced REST API
connector-service	13034	Simple REST API (used by MCP)
configurator-web	13035	Web UI for configuration

Health checks

curl http://localhost:9999/healthz/ready
curl http://localhost:13034/healthz
curl http://localhost:13033/api/v1/health

MCP Configuration

Set the CONVERSION_SERVICE_URL environment variable to point to the Conversion Service Simple API. Default: http://localhost:13034.

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "conversion-service": {
      "command": "python3",
      "args": ["<path-to-repo>/server.py"],
      "env": {
        "CONVERSION_SERVICE_URL": "http://localhost:13034"
      }
    }
  }
}

Or via CLI:

claude mcp add conversion-service -- python3 <path-to-repo>/server.py

Claude Desktop

Add to claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/, on Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "conversion-service": {
      "command": "python",
      "args": ["<path-to-repo>/server.py"],
      "env": {
        "CONVERSION_SERVICE_URL": "http://localhost:13034"
      }
    }
  }
}

API Endpoints

Each profile supports two input modes:

• JSON (/http.inputstructured/<profile>) -- structured JSON with base64 content or URL references. Used by most tools.
• Plain HTTP (/http.input/<profile>) -- multipart/form-data for large files (>100 MB). Used by convert_large_file.

Options

• DOC.PASSWORD -- unlock password-protected documents
• META.AUTHOR -- set author metadata on output PDF
• OPTIMIZEPROFILE -- print, web, or max (email) optimization