Conversion Service MCP Server

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