Cute Pandoc MCP Server

An MCP (Model Context Protocol) server that provides isolated pandoc execution environments for document conversion tasks.

Features

• Isolated Execution: Each request runs in a fresh Docker container
• File Access Control: Only explicitly provided files are accessible
• Worker Pool: Configurable concurrent execution limits
• Security: Network disabled, resource limits, non-root execution
• Full Pandoc Support: All pandoc formats, LaTeX/XeLaTeX for PDF generation, custom templates
• HTTP File Upload: Upload files via HTTP endpoints in HTTP transport mode

Prerequisites

• Go 1.24+
• A container runtime (any of the following):
  • Docker Desktop
  • Colima
  • Lima
  • Podman
  • Rancher Desktop

The server auto-detects common Docker socket locations, so it works out of the box with most setups.

Quick Start

1. Build the Server

go mod tidy
go build -o cute-pandoc-server .

2. Run the Server

Default: Pull from Docker Hub (Instant Start)

The server uses a pre-built Docker Hub image by default for instant startup:

./cute-pandoc-server

Override: Local Build

To build from CutePandoc.Dockerfile instead of pulling:

BUILD_LOCAL=true ./cute-pandoc-server

Note: Local build may take a few minutes the first time as it downloads the pandoc/latex base image and installs dependencies.

Stdio mode (for MCP clients like Claude Desktop):

./cute-pandoc-server

HTTP mode (with file upload support):

./cute-pandoc-server -t http
# or
TRANSPORT=http ./cute-pandoc-server

# With custom storage settings
TRANSPORT=http UPLOAD_TTL=2h MAX_UPLOAD_SIZE=209715200 ./cute-pandoc-server

Configuration

Configure via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | MAX_WORKERS | 5 | Maximum concurrent container executions | | QUEUE_SIZE | 10 | Max pending requests in queue | | ACQUIRE_TIMEOUT | 30s | Time to wait for an available worker | | EXECUTION_TIMEOUT | 120s | Max script execution time | | MAX_MEMORY_MB | 1024 | Memory limit per container in MB | | MAX_CPU | 1.0 | CPU limit per container | | DOCKER_IMAGE | sagacient/cutepandoc:latest | Docker image to use | | BUILD_LOCAL | false | Set to true to build from CutePandoc.Dockerfile instead of pulling | | NETWORK_DISABLED | true | Disable network in containers | | TRANSPORT | stdio | Transport type: stdio or http | | HTTP_PORT | 8080 | Port for HTTP transport | | STORAGE_DIR | ~/.cache/cute-pandoc/uploads (native) or /storage (Docker) | Directory for uploaded files | | UPLOAD_TTL | 1h | Auto-delete uploaded files after this duration (e.g., 30m, 2h) | | MAX_UPLOAD_SIZE | 104857600 (100MB) | Maximum upload file size in bytes | | SCAN_UPLOADS | true | Enable ClamAV malware scanning for uploaded files | | SCAN_ON_FAIL | reject | Behavior when scanner unavailable: reject or allow | | TEMP_DIR | /tmp/cute-pandoc (Docker) or ~/.cache/cute-pandoc/tmp (native) | Temp directory for script execution (must be shared mount for Docker-in-Docker) | | OUTPUT_DIR | (empty) | Base directory for execution outputs. Each execution gets an isolated subdirectory (exec-xxx). | | OUTPUT_TTL | 24h | Auto-delete execution outputs after this duration (e.g., 12h, 48h) |

MCP Tools

run_pandoc_command

Execute pandoc with arbitrary command-line arguments. All output files are automatically saved to the execution output directory and can be retrieved using list_outputs and get_output tools.

{
  "args": ["-f", "markdown", "-t", "pdf", "input.md", "-o", "output.pdf"],
  "files": ["/path/to/input.md"],
  "post_script": "",
  "timeout": 120
}

Helper functions available in post-processing scripts:

• resolve_path(original_path) - Convert original file path to container path
• save_output(source_file, filename) - Copy a file

... View full README on GitHub