Skip to content

USAGE.md

Latest commit

 

History

History
492 lines (357 loc) · 10.4 KB

USAGE.md

File metadata and controls

492 lines (357 loc) · 10.4 KB

Using GroupDocs.Conversion MCP Server

This guide covers everything you need to connect an MCP host to the server and start converting documents.

Table of contents

  1. Choose a transport mode
  2. Start the server
  3. Connect your MCP host
  4. Call the convert_document tool
  5. Conversion examples
  6. Working with protected documents
  7. Overwriting existing output
  8. File size and timeout limits
  9. Health checks
  10. Troubleshooting

1. Choose a transport mode

The server supports two MCP transports, selected with the MCP_TRANSPORT environment variable.

Mode Value Best for
STDIO stdio (default) Claude Desktop, local MCP hosts, development
HTTP http Docker, remote access, multi-client setups

2. Start the server

STDIO — run locally with .NET

# Minimum required: set your input and output folders
export MCP_TRANSPORT=stdio
export INPUT_ROOT=/home/user/documents/input
export OUTPUT_ROOT=/home/user/documents/output
export WORK_ROOT=/tmp/gdconv

mkdir -p $INPUT_ROOT $OUTPUT_ROOT $WORK_ROOT

dotnet run --project src/GroupDocs.Conversion.McpServer

The process will stay open, reading MCP messages from stdin and writing responses to stdout.

HTTP — run with Docker Compose

# Clone and enter the repo
git clone https://github.com/groupdocs-conversion/groupdocs-conversion-mcp.git
cd groupdocs-conversion-mcp

# (Optional) add your GroupDocs license
mkdir -p docker/secrets
cp /path/to/your.lic docker/secrets/groupdocs-license.lic

# Put source documents in samples/input
cp /path/to/mydoc.docx samples/input/

# Start
docker compose -f docker/docker-compose.yml up -d

The server is now available at http://localhost:8080/mcp.

HTTP — run with Docker directly

docker run -d \
  --name gdconv-mcp \
  -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e INPUT_ROOT=/data/in \
  -e OUTPUT_ROOT=/data/out \
  -e WORK_ROOT=/data/work \
  -v /srv/gdconv/in:/data/in:ro \
  -v /srv/gdconv/out:/data/out \
  -v /srv/gdconv/work:/data/work \
  groupdocs/groupdocs-conversion-mcp:1.0.0

3. Connect your MCP host

Claude Desktop — STDIO

Open claude_desktop_config.json (location: ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows) and add:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/src/GroupDocs.Conversion.McpServer"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "INPUT_ROOT": "/home/user/documents/input",
        "OUTPUT_ROOT": "/home/user/documents/output",
        "WORK_ROOT": "/tmp/gdconv"
      }
    }
  }
}

Restart Claude Desktop. The convert_document tool will appear in the tool list.

Claude Desktop — HTTP (Docker)

{
  "mcpServers": {
    "groupdocs-conversion": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

VS Code (MCP extension)

In your VS Code settings.json:

{
  "mcp.servers": {
    "groupdocs-conversion": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Cursor

In .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "groupdocs-conversion": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Custom MCP client (HTTP)

Send a standard MCP tools/call request to http://localhost:8080/mcp:

POST /mcp HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "convert_document",
    "arguments": {
      "sourcePath": "reports/q1.docx",
      "targetFormat": "pdf",
      "outputPath": "converted/q1.pdf"
    }
  }
}

4. Call the convert_document tool

Parameters

Parameter Type Required Description
sourcePath string Yes Relative path to the source file inside INPUT_ROOT
targetFormat string Yes Target format string (see table below)
outputPath string Yes Relative path for the output file inside OUTPUT_ROOT
overwrite boolean No Overwrite output if it already exists. Default: false
password string No Password to open a protected source document

Supported target formats

Value Output type
pdf PDF document
docx Word document
xlsx Excel spreadsheet
pptx PowerPoint presentation
html HTML page
txt Plain text
jpg JPEG image
png PNG image

Prompt examples for AI assistants

When the MCP server is connected, you can instruct the AI naturally:

"Convert the file reports/q1.docx to PDF and save it as converted/q1.pdf."

"Turn slides/deck.pptx into a PDF."

"Convert data/export.xlsx to HTML and put the result in web/export.html."

"I have a password-protected Word file at contracts/nda.docx with password secret123. Convert it to PDF."

The AI will call convert_document with the appropriate arguments and report back the result.

5. Conversion examples

Word → PDF

{
  "sourcePath": "documents/report.docx",
  "targetFormat": "pdf",
  "outputPath": "pdf/report.pdf"
}

Success response:

{
  "success": true,
  "sourcePath": "documents/report.docx",
  "outputPath": "pdf/report.pdf",
  "targetFormat": "pdf",
  "durationMs": 934,
  "outputExists": true,
  "outputSizeBytes": 204800
}

PDF → Word

{
  "sourcePath": "scanned/invoice.pdf",
  "targetFormat": "docx",
  "outputPath": "editable/invoice.docx"
}

Excel → PDF

{
  "sourcePath": "data/budget.xlsx",
  "targetFormat": "pdf",
  "outputPath": "exports/budget.pdf"
}

PowerPoint → PDF

{
  "sourcePath": "presentations/deck.pptx",
  "targetFormat": "pdf",
  "outputPath": "exports/deck.pdf"
}

Document → HTML

{
  "sourcePath": "articles/post.docx",
  "targetFormat": "html",
  "outputPath": "web/post.html"
}

Document → Image

{
  "sourcePath": "thumbnails/cover.docx",
  "targetFormat": "png",
  "outputPath": "images/cover.png"
}

6. Working with protected documents

If the source document is password-protected, pass the password in the password field:

{
  "sourcePath": "contracts/nda.docx",
  "targetFormat": "pdf",
  "outputPath": "exports/nda.pdf",
  "password": "MySecretPassword"
}

Note: The password is used only to open the source document. It is not applied to the output file.

7. Overwriting existing output

By default, if the output file already exists the tool returns an error:

{
  "success": false,
  "errorCode": "output_exists",
  "message": "Output file already exists: 'exports/report.pdf'"
}

To overwrite, set overwrite to true:

{
  "sourcePath": "documents/report.docx",
  "targetFormat": "pdf",
  "outputPath": "exports/report.pdf",
  "overwrite": true
}

You can also enable overwrite globally for all requests by setting the environment variable ALLOW_OVERWRITE=true when starting the server.

8. File size and timeout limits

Limit Default Environment variable
Maximum source file size 200 MB MAX_INPUT_FILE_MB
Conversion timeout 300 seconds CONVERSION_TIMEOUT_SECONDS
Max parallel conversions 2 MAX_CONCURRENT_CONVERSIONS

If a file exceeds the size limit:

{
  "success": false,
  "errorCode": "input_too_large",
  "message": "Source file exceeds maximum size of 200 MB."
}

If conversion times out:

{
  "success": false,
  "errorCode": "conversion_timeout",
  "message": "Conversion timed out."
}

9. Health checks

These endpoints are available in HTTP transport mode.

Liveness — is the process alive?

curl http://localhost:8080/health/live
# 200 OK — process is running

Readiness — is the server ready to accept conversions?

curl http://localhost:8080/health/ready
# 200 OK  — storage roots exist and work folder is writable
# 503     — one or more roots are missing or not writable

Use /health/ready as the Docker or Kubernetes readiness probe.

10. Troubleshooting

"source_not_found" error

The file path is relative to INPUT_ROOT. Check that:

  • The file exists at the correct path under INPUT_ROOT
  • The Docker volume is mounted and the file is visible inside the container
# Verify the file is accessible inside the container
docker exec gdconv-mcp ls /data/in/documents/

"source_outside_allowed_root" or "output_outside_allowed_root"

The path contains .., is absolute, or escapes the configured root. Use only relative paths that stay inside INPUT_ROOT / OUTPUT_ROOT:

{ "sourcePath": "subfolder/file.docx" }   // correct
{ "sourcePath": "../other/file.docx" }     // rejected
{ "sourcePath": "/absolute/file.docx" }    // rejected

"unsupported_target_format"

Only the formats listed in section 4 are supported. Check spelling; the value is case-insensitive (PDF, pdf, and Pdf all work).

Output directory does not exist

The server creates intermediate output directories automatically. You do not need to pre-create them.

Evaluation watermarks in output

This means the server is running without a GroupDocs license. Supply a license file:

# Docker
-v /path/to/your.lic:/run/secrets/groupdocs-license.lic:ro
-e GROUPDOCS_LICENSE_PATH=/run/secrets/groupdocs-license.lic

Server logs

# Docker
docker logs gdconv-mcp --follow

# Local
dotnet run --project src/GroupDocs.Conversion.McpServer 2>&1 | tee conversion.log

Each conversion request is logged with a short correlation ID, source path, target format, duration, and result code.

Conversion is slow or times out

  • Increase CONVERSION_TIMEOUT_SECONDS for large or complex documents
  • Reduce MAX_CONCURRENT_CONVERSIONS if the host is memory-constrained (each GroupDocs conversion can use significant RAM for large files)
  • Ensure WORK_ROOT is on fast local storage, not a network share