Skip to main content
Glama

mcp-pandoc: Ein MCP-Server zur Dokumentkonvertierung

Offiziell im Open-Source-Projekt der Model Context Protocol-Server enthalten. 🎉

Überblick

Ein Model Context Protocol-Server zur Dokumentformatkonvertierung mit pandoc . Dieser Server bietet Tools zum Konvertieren von Inhalten zwischen verschiedenen Dokumentformaten unter Beibehaltung von Formatierung und Struktur.

Bitte beachten Sie, dass sich mcp-pandoc derzeit in der frühen Entwicklungsphase befindet. Die PDF-Unterstützung ist in der Entwicklung, und die Funktionalität und die verfügbaren Tools können sich im Zuge der kontinuierlichen Verbesserung des Servers ändern und erweitern.

Anerkennung: Dieses Projekt verwendet das Pandoc Python-Paket zur Dokumentkonvertierung, das die Grundlage für dieses Projekt bildet.

Related MCP server: md2pdf-mcp

Demo

mcp-pandoc – v1: Nahtlose Dokumentformatkonvertierung für Claude mithilfe des MCP-Servers

🎥 Auf YouTube ansehen

Mehr folgt ...

Werkzeuge

  1. convert-contents

    • Wandelt Inhalte zwischen unterstützten Formaten um

    • Eingänge:

      • contents (Zeichenfolge): Zu konvertierender Quellinhalt (erforderlich, wenn keine Eingabedatei angegeben ist)

      • input_file (Zeichenfolge): Vollständiger Pfad zur Eingabedatei (erforderlich, wenn kein Inhalt angegeben ist)

      • input_format (Zeichenfolge): Quellformat des Inhalts (standardmäßig Markdown)

      • output_format (Zeichenfolge): Zielformat (standardmäßig Markdown)

      • output_file (Zeichenfolge): Vollständiger Pfad zur Ausgabedatei (erforderlich für die Formate pdf, docx, rst, latex, epub)

    • Unterstützte Eingabe-/Ausgabeformate:

      • Abschlag

      • html

      • pdf

      • docx

      • zuerst

      • Latex

      • epub

      • txt

    • Hinweis: Für erweiterte Formate (pdf, docx, rst, latex, epub) ist ein Ausgabedateipfad erforderlich

Unterstützte Formate

Derzeit unterstützte Formate:

Basisformate (direkte Konvertierung):

  • Nur-Text (.txt)

  • Markdown (.md)

  • HTML (.html)

Erweiterte Formate (erfordert vollständige Dateipfade):

  • PDF (.pdf) – erfordert die Installation von TeX Live

  • DOCX (.docx)

  • RST (.rst)

  • LaTeX (.tex)

  • EPUB (.epub)

Hinweis: Für erweiterte Formate:

  1. Es werden vollständige Dateipfade mit Dateinamen und Erweiterung benötigt.

  2. Für die PDF-Konvertierung ist eine Installation von TeX Live erforderlich (siehe Abschnitt „Wichtige Anforderungen“ -> Für macOS: brew install texlive )

  3. Wenn kein Ausgabepfad angegeben ist:

    • Basisformate: Zeigt konvertierte Inhalte im Chat an

    • Erweiterte Formate: Kann im temporären Systemverzeichnis (/tmp/ auf Unix-Systemen) gespeichert werden

Nutzung und Konfiguration

HINWEIS: Stellen Sie sicher, dass Sie die Installation der unten unter „Kritische Anforderungen“ aufgeführten erforderlichen Pakete abschließen.

Um die veröffentlichte zu verwenden

{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

⚠️ Wichtige Hinweise

Kritische Anforderungen

  1. Pandoc-Installation

  • Erforderlich : Installieren Sie pandoc – die zentrale Dokumentkonvertierungs-Engine

  • Installation:

    # macOS
    brew install pandoc
    
    # Ubuntu/Debian
    sudo apt-get install pandoc
    
    # Windows
    # Download installer from: https://pandoc.org/installing.html
  • Überprüfen : pandoc --version

  1. Installation des UV-Pakets

  • Erforderlich : Installieren Sie uv Paket (beinhaltet den Befehl uvx ).

  • Installation:

    # macOS
    brew install uv
    
    # Windows/Linux
    pip install uv
  • Überprüfen : uvx --version

  1. Voraussetzungen für die PDF-Konvertierung: Nur erforderlich, wenn Sie PDF konvertieren und speichern müssen

  • TeX Live muss vor der PDF-Konvertierung installiert sein

  • Installationsbefehle:

    # Ubuntu/Debian
    sudo apt-get install texlive-xetex
    
    # macOS
    brew install texlive
    
    # Windows
    # Install MiKTeX or TeX Live from:
    # https://miktex.org/ or https://tug.org/texlive/
  1. Anforderungen für den Dateipfad

  • Beim Speichern oder Konvertieren von Dateien MÜSSEN Sie vollständige Dateipfade einschließlich Dateiname und Erweiterung angeben

  • Das Tool generiert nicht automatisch Dateinamen oder Erweiterungen

Beispiele

✅ Richtige Anwendung:

# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

❌ Falsche Verwendung:

# Missing filename and extension
"Save this as PDF in /documents/"

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

Häufige Probleme und Lösungen

  1. PDF-Konvertierung schlägt fehl

    • Fehler: „xelatex nicht gefunden“

    • Lösung: Installieren Sie zuerst TeX Live (siehe Installationsbefehle oben)

  2. Dateikonvertierung schlägt fehl

    • Fehler: „Ungültiger Dateipfad“

    • Lösung: Vollständigen Pfad inklusive Dateiname und Erweiterung angeben

    • Beispiel: /path/to/document.pdf statt nur /path/to/

  3. Formatkonvertierung schlägt fehl

    • Fehler: „Nicht unterstütztes Format“

    • Lösung: Verwenden Sie nur unterstützte Formate:

      • Grundlegend: txt, html, Markdown

      • Erweitert: pdf, docx, rst, latex, epub

Schnellstart

Installieren

Option 1: Manuelle Installation über die Konfigurationsdatei claude_desktop_config.json

  • Unter MacOS: open ~/Library/Application\ Support/Claude/claude_desktop_config.json

  • Unter Windows: %APPDATA%/Claude/claude_desktop_config.json

a) Nur für die lokale Entwicklung und Beiträge zu diesem Repo

ℹ️ Ersetzen Sie durch Ihren lokal geklonten Projektpfad

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

b) Konfiguration der veröffentlichten Server - Verbraucher sollten diese Konfiguration verwenden

"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": [
      "mcp-pandoc"
    ]
  }
}

Option 2: Automatische Installation der Konfiguration veröffentlichter Server über Smithery

Führen Sie den folgenden Bash-Befehl aus, um veröffentlichtes mcp-pandoc pypi für Claude Desktop automatisch über Smithery zu installieren:

npx -y @smithery/cli install mcp-pandoc --client claude
  • Wenn Sie auf ein Problem stoßen, verwenden Sie anstelle dieser Befehlszeilenschnittstelle direkt die oben stehende „Konfiguration veröffentlichter Server“.

Hinweis : Um lokal konfiguriertes mcp-pandoc zu verwenden, befolgen Sie den obigen Schritt „Konfiguration von Entwicklungs-/unveröffentlichten Servern“.

Entwicklung

Erstellen und Veröffentlichen

So bereiten Sie das Paket für die Verteilung vor:

  1. Abhängigkeiten synchronisieren und Sperrdatei aktualisieren:

uv sync
  1. Erstellen Sie Paketverteilungen:

uv build

Dadurch werden Quell- und Wheel-Distributionen im Verzeichnis dist/ erstellt.

  1. Auf PyPI veröffentlichen:

uv publish

Hinweis: Sie müssen PyPI-Anmeldeinformationen über Umgebungsvariablen oder Befehlsflags festlegen:

  • Token: --token oder UV_PUBLISH_TOKEN

  • Oder Benutzername/Passwort: --username / UV_PUBLISH_USERNAME und --password / UV_PUBLISH_PASSWORD

Debuggen

Da MCP-Server über stdio laufen, kann das Debuggen eine Herausforderung darstellen. Für ein optimales Debugging empfehlen wir dringend die Verwendung des MCP Inspector .

Sie können den MCP Inspector über npm mit diesem Befehl starten:

npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc

Beim Start zeigt der Inspector eine URL an, auf die Sie in Ihrem Browser zugreifen können, um mit dem Debuggen zu beginnen.


Beitragen

Wir freuen uns über Beiträge zur Verbesserung von mcp-pandoc! So können Sie mitmachen:

  1. Probleme melden : Haben Sie einen Fehler gefunden oder möchten Sie eine Funktion aktivieren? Melden Sie ein Problem auf unserer GitHub-Problemseite .

  2. Pull Requests senden : Verbessern Sie die Codebasis oder fügen Sie Funktionen hinzu, indem Sie einen Pull Request erstellen.


Available Tools

1 tool
convert-contentsA

Converts content between different formats. Transforms input content from any supported format into the specified output format.

🚨 CRITICAL REQUIREMENTS - PLEASE READ:

  1. PDF Conversion:

    • You MUST install TeX Live BEFORE attempting PDF conversion:

    • Ubuntu/Debian: sudo apt-get install texlive-xetex

    • macOS: brew install texlive

    • Windows: Install MiKTeX or TeX Live from https://miktex.org/ or https://tug.org/texlive/

    • PDF conversion will FAIL without this installation

  2. File Paths - EXPLICIT REQUIREMENTS:

    • When asked to save or convert to a file, you MUST provide:

      • Complete directory path

      • Filename

      • File extension

    • Example request: 'Write a story and save as PDF'

    • You MUST specify: '/path/to/story.pdf' or 'C:\Documents\story.pdf'

    • The tool will NOT automatically generate filenames or extensions

  3. File Location After Conversion:

    • After successful conversion, the tool will display the exact path where the file is saved

    • Look for message: 'Content successfully converted and saved to: [file_path]'

    • You can find your converted file at the specified location

    • If no path is specified, files may be saved in system temp directory (/tmp/ on Unix systems)

    • For better control, always provide explicit output file paths

Supported formats:

  • Basic (returned inline): txt, html, markdown, ipynb

  • Advanced (REQUIRE complete file paths): pdf, docx, rst, latex, epub, odt, pptx

  • pptx is WRITE-ONLY: it can be produced, but not used as an input format ✅ CORRECT Usage Examples:

  1. 'Convert this text to HTML' (basic conversion)

    • Tool will show converted content

  2. 'Save this text as PDF at /documents/story.pdf'

    • Correct: specifies path + filename + extension

    • Tool will show: 'Content successfully converted and saved to: /documents/story.pdf'

❌ INCORRECT Usage Examples:

  1. 'Save this as PDF in /documents/'

    • Missing filename and extension

  2. 'Convert to PDF'

    • Missing complete file path

When requesting conversion, ALWAYS specify:

  1. The content or input file

  2. The desired output format

  3. For advanced formats: complete output path + filename + extension Example: 'Convert this markdown to PDF and save as /path/to/output.pdf'

🎨 DOCX, ODT & PPTX STYLING: 4. Custom Styling with Reference Documents:

  • Use reference_doc parameter to apply professional styling to DOCX, ODT and PPTX output

  • The reference document MUST match the output format: .docx for docx, .odt for odt, .pptx for pptx

  • Create custom templates with your branding, fonts, and formatting

  • Perfect for corporate reports, academic papers, and professional documents

  • Example: 'Convert this report to DOCX using /templates/corporate-style.docx as reference and save as /reports/Q4-report.docx'

🎯 PANDOC FILTERS (NEW FEATURE): 5. Pandoc Filter Support:

  • Use filters parameter to apply custom Pandoc filters during conversion

  • Filters are Python scripts that modify document content during processing

  • Perfect for Mermaid diagram conversion, custom styling, and content transformation

  • Example: 'Convert this markdown with mermaid diagrams to DOCX using filters=["./filters/mermaid-to-png-vibrant.py"] and save as /reports/diagram-report.docx'

📋 Creating Reference Documents:

  • Generate template: pandoc -o template.docx --print-default-data-file reference.docx

  • Customize in Word/LibreOffice: fonts, colors, headers, margins

  • Use for consistent branding across all documents

📋 Filter Requirements:

  • Filters must be executable Python scripts

  • Use absolute paths or paths relative to current working directory

  • Filters are applied in the order specified

  • Common filters: mermaid conversion, color processing, table formatting

📄 Defaults File Support (NEW FEATURE): 7. Pandoc Defaults File Support:

  • Use defaults_file parameter to specify a YAML configuration file

  • Similar to using pandoc -d option in the command line

  • Allows setting multiple options in a single file

  • Options in the defaults file can include filters, reference-doc, and other Pandoc options

  • Example: 'Convert this markdown to DOCX using defaults_file="/path/to/defaults.yaml" and save as /reports/report.docx'

Note: After conversion, always check the success message for the exact file location.

Inputs: filters, contents, input_file, output_file, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool, so there is no possibility of an agent mistaking it for another. Its purpose is clearly defined as content conversion, with no overlapping tools.

    Naming Consistency5/5

    Although there is only one tool, the name 'convert-contents' follows a clear verb_noun convention and is semantically appropriate. With no other tools, there are no naming conflicts or mixed conventions.

    Tool Count3/5

    A single tool for Pandoc conversion feels minimal, though it can cover many conversions through its parameters. It is on the thin side of the acceptable range for a focused converter server.

    Completeness5/5

    The tool supports conversion across a wide range of formats, including inline returns and file outputs, plus advanced options like reference documents, filters, and defaults files. For a conversion-only server, this covers the domain thoroughly with no obvious operational gaps.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers