tools-only Pandoc Server
Overview
The Pandoc MCP Server provides powerful document conversion capabilities using the versatile pandoc tool. This Go-based server enables text conversion between 30+ document formats with support for standalone documents, table of contents generation, and custom metadata. It serves as a bridge between the MCP protocol and pandoc's extensive format conversion capabilities.
Key Features
- Convert between 30+ document formats: Supports markdown, HTML, LaTeX, PDF, DOCX, EPUB, and many more
- Standalone document generation: Create complete, self-contained documents
- Table of contents support: Automatically generate TOCs for supported formats
- Custom metadata handling: Add titles, authors, and other metadata to documents
- Format discovery tools: List available input and output formats
- Health monitoring: Check pandoc installation and version information
Quick Start
Prerequisites
Pandoc must be installed on the system:
# Ubuntu/Debian
sudo apt install pandoc
# macOS
brew install pandoc
# Windows: Download from pandoc.org
# Verify installation
pandoc --version
Go 1.23 or later for building from source.
Installation
From Source
# Clone the repository
git clone <repository-url>
cd pandoc-server
# Install dependencies
go mod download
# Build the server
make build
Using Docker
# Build the Docker image
docker build -t pandoc-server .
# Run the container
docker run -i pandoc-server
Running the Server
# Run the built server
./dist/pandoc-server
# Or with ContextForge for HTTP/SSE access
python3 -m mcpgateway.translate --stdio "./dist/pandoc-server" --port 9000
Available Tools
pandoc
Convert text from one format to another using pandoc.
Parameters:
from(required): Input format (e.g., markdown, html, latex, rst, docx, epub)to(required): Output format (e.g., html, markdown, latex, pdf, docx, plain)input(required): The text content to convertstandalone: Produce a standalone document (default: false)title: Document title for standalone documentsmetadata: Additional metadata in key=value formattoc: Include table of contents (default: false)
list-formats
List available pandoc input and output formats.
Parameters:
type: Format type to list - 'input', 'output', or 'all' (default: 'all')
health
Check if pandoc is installed and return version information.
Returns:
- Pandoc installation status
- Version information
- Available features and extensions
Configuration
MCP Client Configuration
{
"mcpServers": {
"pandoc-server": {
"command": "./dist/pandoc-server"
}
}
}
Via ContextForge
{
"mcpServers": {
"pandoc-server": {
"command": "python3",
"args": ["-m", "mcpgateway.translate", "--stdio", "./dist/pandoc-server", "--port", "9000"]
}
}
}
Examples
Convert Markdown to HTML
{
"tool": "pandoc",
"arguments": {
"from": "markdown",
"to": "html",
"input": "# Hello World\n\nThis is **bold** text.",
"standalone": true,
"title": "My Document"
}
}
Response:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<title>My Document</title>
</head>
<body>
<h1 id="hello-world">Hello World</h1>
<p>This is <strong>bold</strong> text.</p>
</body>
</html>
Convert HTML to Markdown
{
"tool": "pandoc",
"arguments": {
"from": "html",
"to": "markdown",
"input": "<h1>Title</h1><p>This is a <em>paragraph</em> with <strong>formatting</strong>.</p>"
}
}
Create LaTeX Document with TOC
{
"tool": "pandoc",
"arguments": {
"from": "markdown",
"to": "latex",
"input": "# Introduction\n\nThis is the introduction.\n\n# Main Content\n\nThis is the main content.\n\n# Conclusion\n\nThis is the conclusion.",
"standalone": true,
"title": "Research Paper",
"toc": true,
"metadata": "author=John Doe,date=2024-01-15"
}
}
Convert DOCX to Plain Text
{
"tool": "pandoc",
"arguments": {
"from": "docx",
"to": "plain",
"input": "<base64-encoded-docx-content>"
}
}
List Available Formats
{
"tool": "list-formats",
"arguments": {
"type": "input"
}
}
Response:
{
"success": true,
"format_type": "input",
"formats": [
"markdown",
"html",
"latex",
"rst",
"docx",
"epub",
"json",
"csv",
"mediawiki",
"org"
]
}
Check Pandoc Health
{
"tool": "health",
"arguments": {}
}
Response:
{
"success": true,
"pandoc_installed": true,
"version": "2.19.2",
"features": ["pdf-engine", "lua-filters", "bibliography"],
"status": "healthy"
}
Integration
With ContextForge
The Pandoc server integrates seamlessly with ContextForge for HTTP and SSE access:
# Start pandoc server via ContextForge
python3 -m mcpgateway.translate --stdio "./dist/pandoc-server" --port 9000
# Register with ContextForge
curl -X POST http://localhost:8000/gateways \
-H "Content-Type: application/json" \
-d '{
"name": "pandoc-server",
"url": "http://localhost:9000",
"description": "Document conversion server using Pandoc"
}'
Programmatic Usage
// Example Go client usage
package main
import (
"context"
"fmt"
"log"
"github.com/your-org/mcp-go-client"
)
func main() {
client, err := mcp.NewStdioClient("./dist/pandoc-server")
if err != nil {
log.Fatal(err)
}
defer client.Close()
// Convert markdown to HTML
result, err := client.CallTool(context.Background(), "pandoc", map[string]any{
"from": "markdown",
"to": "html",
"input": "# Hello\n\nWorld!",
"standalone": true,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(result)
}
Supported Formats
Pandoc supports numerous input and output formats. Use the list-formats tool to see all available formats on your system.
Common Input Formats
- markdown: Pandoc's extended Markdown
- html: HTML documents
- latex: LaTeX documents
- rst: reStructuredText
- docx: Microsoft Word documents
- epub: EPUB e-books
- json: Pandoc JSON format
- csv: Comma-separated values
- mediawiki: MediaWiki markup
- org: Emacs Org mode
Common Output Formats
- html: HTML documents
- markdown: Markdown format
- latex: LaTeX documents
- pdf: PDF documents (requires LaTeX)
- docx: Microsoft Word documents
- epub: EPUB e-books
- plain: Plain text
- json: Pandoc JSON format
- asciidoc: AsciiDoc format
- rst: reStructuredText
Advanced Features
Metadata Handling
{
"tool": "pandoc",
"arguments": {
"from": "markdown",
"to": "html",
"input": "# Document\n\nContent here.",
"standalone": true,
"title": "My Article",
"metadata": "author=John Doe,date=2024-01-15,keywords=documentation pandoc"
}
}
Table of Contents Generation
{
"tool": "pandoc",
"arguments": {
"from": "markdown",
"to": "html",
"input": "# Chapter 1\n\n## Section 1.1\n\n### Subsection 1.1.1\n\n# Chapter 2\n\n## Section 2.1",
"standalone": true,
"toc": true,
"title": "Technical Manual"
}
}
Batch Processing
// Example batch conversion
documents := []struct {
input string
format string
}{
{"# Doc 1\n\nContent 1", "html"},
{"# Doc 2\n\nContent 2", "latex"},
{"# Doc 3\n\nContent 3", "docx"},
}
for i, doc := range documents {
result, err := client.CallTool(context.Background(), "pandoc", map[string]any{
"from": "markdown",
"to": doc.format,
"input": doc.input,
"standalone": true,
"title": fmt.Sprintf("Document %d", i+1),
})
if err != nil {
log.Printf("Error converting doc %d: %v", i+1, err)
continue
}
// Process result...
}
Use Cases
Documentation Workflows
- Convert Markdown documentation to HTML for web publishing
- Generate PDF versions of documentation from Markdown sources
- Transform reStructuredText to various output formats
Content Publishing
- Convert blog posts between different markup formats
- Generate e-books (EPUB) from Markdown sources
- Create presentation slides from Markdown
Academic Writing
- Convert between LaTeX and Word formats for collaboration
- Generate bibliographies and citations
- Create formatted academic papers
Report Generation
- Convert data reports to multiple output formats
- Generate executive summaries in different formats
- Create standardized document templates
Migration Projects
- Convert legacy document formats to modern alternatives
- Batch process document archives
- Standardize document formats across organizations
Error Handling
The server provides comprehensive error handling for:
- Missing Pandoc Installation: Clear error messages with installation guidance
- Unsupported Format Combinations: Validation of input/output format compatibility
- Invalid Input Content: Proper error reporting for malformed documents
- Conversion Failures: Detailed pandoc error messages
- Resource Limits: Handling of large documents and memory constraints
Development
Building from Source
# Format code
make fmt
# Run tests
make test
# Tidy dependencies
make tidy
# Build binary
make build
Testing
# Run all tests
make test
# Test specific functionality
go test -v ./...
# Test with coverage
go test -cover ./...
Docker Development
# Build development image
docker build -t pandoc-server:dev .
# Run tests in container
docker run --rm pandoc-server:dev make test
# Interactive development shell
docker run --rm -it pandoc-server:dev /bin/sh
Performance Considerations
- Pandoc Startup Overhead: Each conversion spawns a new pandoc process
- Large Documents: Memory usage scales with document size
- Complex Formats: PDF generation requires LaTeX installation and is slower
- Concurrent Requests: The server can handle multiple simultaneous conversions
- Caching: Consider implementing caching for frequently converted content
Security Considerations
- Input Validation: The server validates input formats and content
- Process Isolation: Each pandoc conversion runs in a separate process
- Resource Limits: Consider implementing timeouts for long-running conversions
- File System Access: Pandoc may access local files for includes and templates
Limitations
- Format Support: Available formats depend on pandoc installation and features
- Binary Content: Some formats require special handling for binary content
- Template Dependencies: Custom templates and includes may require additional setup
- PDF Generation: Requires LaTeX installation for PDF output
- Large Files: Very large documents may hit memory or processing limits