mcp-pandoc: A Document Conversion MCP Server

已正式纳入 Model Context Protocol 服务开源项目。🎉

概述

一个使用 pandoc 转换文档格式的 Model Context Protocol 服务。此服务提供工具，可在不同文档格式之间转换内容，同时保留格式和结构。

请注意，mcp-pandoc 目前仍处于早期开发阶段。PDF 支持仍在开发中，随着我们不断改进此服务，其功能和可用工具可能会发生变化并扩展。

致谢：本项目使用 Pandoc Python package 进行文档转换，它构成了本项目的基础。

📋 快速参考

刚开始使用 mcp-pandoc？ 请查看 📖 CHEATSHEET.md，了解：

• ⚡ 所有格式的复制粘贴示例
• 🔄 双向转换矩阵
• 🎯 常见工作流和实用技巧
• 🌟 参考文档样式指南

非常适合快速查阅和快速入门！

演示

🎥 在 YouTube 上观看

屏幕截图

更多内容即将推出……

工具

1. convert-contents

   • 在支持的格式之间转换内容

   • 输入：

     • contents (string)：要转换的源内容（如果未提供 input_file，则为必填项）
     • input_file (string)：输入文件的完整路径（如果未提供 contents，则为必填项）
     • input_format (string)：内容的源格式（默认为 markdown）
     • output_format (string)：目标格式（默认为 markdown）
     • output_file (string)：输出文件的完整路径（pdf、docx、rst、latex、epub、odt、pptx 格式必填）
     • reference_doc (string)：用于设置样式的参考文档路径（支持 docx、odt 和 pptx 输出；文件必须与输出格式一致）
     • defaults_file (string)：包含转换选项的 Pandoc defaults 文件（YAML）路径
     • filters (array)：转换时要应用的 Pandoc 筛选器路径列表

   • 按方向列出的支持格式：

     格式	读取	写入
     markdown	✅	✅
     html	✅	✅
     docx	✅	✅
     odt	✅	✅
     rst	✅	✅
     latex	✅	✅
     epub	✅	✅
     ipynb	✅	✅
     txt	✅	✅
     pdf	❌	✅
     pptx	❌	✅

   • 注意：对于高级格式（pdf、docx、rst、latex、epub、odt、pptx），必须提供 output_file 路径

🔧 高级功能

Defaults 文件（YAML 配置）

使用 defaults 文件创建可重复使用、格式一致的转换模板：

# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "Academic Paper"
  author: "Research Team"

用法示例："使用 defaults academic-paper.yaml 将 paper.md 转换为 PDF，并保存为 paper.pdf"

Pandoc 筛选器

应用自定义筛选器以增强处理效果：

用法示例："使用筛选器 ['/path/to/mermaid-filter.py'] 将 docs.md 转换为 HTML，并保存为 docs.html"

💡 如需查看全面的示例和工作流，请参阅 CHEATSHEET.md

📊 支持的格式与转换

双向转换矩阵

行表示源格式，列表示目标格式。PDF 和 PPTX 没有对应的行，因为 pandoc 无法读取它们。

关于仅支持写入格式的说明

PDF 和 PPTX 可以生成，但无法读取。

Pandoc 从未提供过 PDF 读取器。Pandoc 在 3.8.3 版（于 2025-12-01 发布）中新增了 PowerPoint 读取器，但本项目未声明最低 pandoc 版本，而且 Ubuntu 24.04 仍随附 pandoc 3.1.3，因此不提供 pptx 输入。相关问题见 #54 和 #49。

PPTX 输出不需要特定的 pandoc 版本。PowerPoint 写入器自 pandoc 2.0.5 起便已存在。

格式类别

各格式的要求

• PDF (.pdf) - 需要安装 TeX Live
• DOCX (.docx)、ODT (.odt)、PPTX (.pptx) - 支持通过参考文档自定义样式，且参考文档必须与输出格式相同
• 所有其他格式 - 无额外要求

注意：对于高级格式：

1. 必须提供包含文件名和扩展名的完整文件路径
2. 转换 PDF 需要安装 TeX Live（参见“关键要求”部分 -> 对于 macOS：brew install texlive）
3. 未指定输出路径时：
   • 基础格式：在聊天中显示转换后的内容
   • 高级格式：可能会保存在系统临时目录中（Unix 系统上的 /tmp/）

使用与配置

注意：请确保完成下文“关键要求”中提到的必需软件包的安装。

使用已发布版本

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

💡 快速入门：请参阅 CHEATSHEET.md，了解可复制粘贴的示例和常见工作流。

⚠️ 重要说明

关键要求

1. 安装 Pandoc

• 必需：安装 pandoc——核心文档转换引擎

• 安装：

  # macOS
  brew install pandoc
  
  # Ubuntu/Debian
  sudo apt-get install pandoc
  
  # Windows
  # Download installer from: https://pandoc.org/installing.html
  

• 验证：pandoc --version

2. 安装 UV 软件包

• 必需：安装 uv 软件包（包含 uvx 命令）

• 安装：

  # macOS
  brew install uv
  
  # Windows/Linux
  pip install uv
  

• 验证：uvx --version

3. **PDF 转换先决条件：**仅在需要转换并保存 PDF 时才需要

• 尝试转换 PDF 前必须安装 TeX Live

• 安装命令：

  # 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/
  

4. 文件路径要求

• 保存或转换文件时，必须提供包含文件名和扩展名的完整文件路径
• 此工具不会自动生成文件名或扩展名

示例

✅ 正确用法：

# 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"

# Converting to DOCX with a reference document template
"Convert input.md to DOCX using template.docx as reference and save as output.docx"

# Converting to ODT with a reference document template
"Convert input.md to ODT using template.odt as reference and save as output.odt"

# Converting to a branded PowerPoint deck
"Convert slides.md to PPTX using template.pptx as reference and save as deck.pptx"

# Step-by-step reference document workflow
"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" or if you already have one, use that
"Then convert with custom styling: Convert this text to DOCX using /path/to/custom-reference.docx as reference and save as /path/to/styled-output.docx"

❌ 错误用法：

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

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

常见问题与解决方案

1. PDF 转换失败

   • 错误：“找不到 xelatex”
   • 解决方案：先安装 TeX Live（参见上述安装命令）

2. 文件转换失败

   • 错误：“文件路径无效”
   • 解决方案：提供包含文件名和扩展名的完整路径
   • 示例：使用 /path/to/document.pdf，而非仅使用 /path/to/

3. 格式转换失败

   • 错误：“不支持的格式”
   • 解决方案：仅使用支持的格式：
     • 基础：txt、html、markdown
     • 高级：pdf、docx、rst、latex、epub

4. 参考文档问题

   • 错误：“找不到参考文档”
   • 解决方案：确保参考文档路径存在且可访问
   • 错误：“当 output_format 为 'odt' 时，reference_doc 必须是 '.odt' 文件”
   • 解决方案：参考文档必须与输出格式相同。Pandoc 本身不会检查这一点：格式不匹配的参考文档在输出 DOCX 时会被静默忽略，而输出的 ODT 文件则无法打开
   • 注意：参考文档适用于 DOCX、ODT 和 PPTX 输出格式
   • 创建方法：pandoc -o reference.docx --print-default-data-file reference.docx，reference.odt 或 reference.pptx 也同理

快速入门

通过 claude_desktop_config.json 配置文件手动安装

• 在 MacOS 上：open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

a) 仅用于本地开发和为此仓库贡献代码

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

b) 已发布服务配置——使用者应使用此配置

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

• 如果遇到问题，请直接使用上方的“已发布服务配置”，而不要使用此 cli。

注意：若要使用本地配置的 mcp-pandoc，请按照上方的“开发版／未发布服务配置”步骤操作。

开发

测试

要运行全面的测试套件并验证所有受支持的双向转换，请使用以下命令：

uv run pytest tests/test_conversions.py

这可确保向后兼容性，并验证工具的核心功能。

构建和发布

准备分发软件包：

1. 同步依赖项并更新锁文件：

uv sync

2. 构建软件包发行文件：

uv build

这将在 dist/ 目录中创建源代码发行包和 wheel 发行包。

3. 发布到 PyPI：

uv publish

注意：你需要通过环境变量或命令行标志设置 PyPI 凭据：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名／密码：--username／UV_PUBLISH_USERNAME 和 --password／UV_PUBLISH_PASSWORD

调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

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

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 以开始调试。

贡献

欢迎为 mcp-pandoc 贡献代码，帮助改进它！以下是参与方式：

1. 报告问题：发现 Bug 或有功能请求？请在我们的 GitHub Issues 页面提交问题。
2. 提交拉取请求：创建拉取请求，改进代码库或添加功能。