mcp-pandoc：文档转换 MCP 服务器

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

概述

基于 pandoc 的文档格式转换 Model Context Protocol 服务器。该服务器提供工具，可在不同文档格式之间转换内容，同时保留格式和结构。

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

致谢：本项目使用了 Pandoc Python 包 进行文档转换，这是该项目的基础。

📋 快速参考

初次使用 mcp-pandoc？ 请查看 📖 CHEATSHEET.md，了解：

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

非常适合快速查找和快速上手！

演示

🎥 在 YouTube 上观看

截图

更多内容即将推出……

工具

1. convert-contents
   • 在支持的格式之间转换内容
   • 输入：
     • contents（字符串）：要转换的源内容（如果未提供 input_file，则为必填项）
     • input_file（字符串）：输入文件的完整路径（如果未提供 contents，则为必填项）
     • input_format（字符串）：内容的源格式（默认为 markdown）
     • output_format（字符串）：目标格式（默认为 markdown）
     • output_file（字符串）：输出文件的完整路径（对于 pdf、docx、rst、latex、epub 格式，此选项为必填项）
     • reference_doc（字符串）：用于样式的参考文档路径（仅适用于 docx 输出格式）
     • defaults_file（字符串）：包含转换选项的 Pandoc 默认配置文件（YAML）路径
     • filters（数组）：转换过程中要应用的 Pandoc 过滤器路径列表
   • 支持的输入/输出格式：
     • markdown
     • html
     • pdf
     • docx
     • rst
     • latex
     • epub
     • txt
     • ipynb
     • odt
   • 注意：对于高级格式（pdf、docx、rst、latex、epub），必须指定 output_file 路径

🔧 高级功能

默认配置文件（YAML 配置）

使用默认配置文件创建可重复使用的转换模板，以保持一致的格式：

# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "学术论文"
  author: "研究团队"

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

Pandoc 过滤器

应用自定义过滤器以增强处理效果：

使用示例：“将 docs.md 转换为 HTML，使用过滤器 ['/path/to/mermaid-filter.py']，并保存为 docs.html”

💡 有关全面示例和工作流程，请参阅 CHEATSHEET.md

📊 支持的格式与转换

双向转换矩阵

关于 PDF 支持的说明

此工具使用 pandoc 进行转换，可以从上述格式生成 PDF 文件。然而，不支持从 PDF 转换为其他格式。因此，PDF 应被视为仅用于输出的格式。

格式分类

格式要求

• PDF (.pdf) - 需要安装 TeX Live
• DOCX (.docx) - 支持通过参考文档自定义样式
• 其他所有格式 - 无额外要求

注意：对于高级格式：

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
  # 从 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
  # 从以下网址安装 MiKTeX 或 TeX Live：
  # https://miktex.org/ 或 https://tug.org/texlive/
  

4. 文件路径要求

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

示例

✅ 正确用法：

# 将内容转换为 PDF 并保存为 /path/to/document.pdf
“将这段文字转换为 PDF，并保存为 /path/to/document.pdf”

# 在不同文件格式之间转换
“将 /path/to/input.md 转换为 PDF，并保存为 /path/to/output.pdf”

# 使用参考文档模板将 Markdown 转换为 DOCX
“使用 template.docx 作为参考，将 input.md 转换为 DOCX，并保存为 output.docx”

# 分步参考文档工作流程
“首先创建一个参考文档：pandoc -o custom-reference.docx --print-default-data-file reference.docx”，或者如果你已经有现成的参考文档，就直接使用它。
“然后进行自定义样式转换：将这段文字转换为 DOCX，使用 /path/to/custom-reference.docx 作为参考，并保存为 /path/to/styled-output.docx”

❌ 错误用法：

# 缺少文件名和扩展名
“把这个保存为 PDF，放在 /documents/ 目录下”

# 缺少完整路径
“把这个转换为 PDF”

# 缺少扩展名
“保存为 /documents/story”

常见问题及解决方案

1. PDF 转换失败

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

2. 文件转换失败

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

3. 格式转换失败

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

4. 参考文档问题

   • 错误信息：“参考文档未找到”
   • 解决方案：确保参考文档的路径存在且可访问
   • 注意：参考文档仅适用于 DOCX 输出格式
   • 如何创建：pandoc -o reference.docx --print-default-data-file reference.docx

快速入门

通过 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/ 目录下生成源码和轮子分发文件。

3. 发布到 PyPI：

uv publish

注意：你需要通过环境变量或命令行参数设置 PyPI 凭证：

• Token：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于 MCP 服务器通过标准输入输出运行，调试可能较为困难。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP 侦查器：

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

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

贡献

我们欢迎对 mcp-pandoc 的贡献！以下是您可以参与的方式：

1. 报告问题：发现 bug 或有功能需求？请在我们的 GitHub Issues 页面上提交一个问题。
2. 提交 Pull Request：通过创建 Pull Request 来改进代码库或添加新功能。

mcp-pandoc 快速上手指南

mcp-pandoc 是一个基于 Model Context Protocol (MCP) 的文档格式转换服务器，利用强大的 Pandoc 引擎，帮助你在不同文档格式（如 Markdown, HTML, PDF, DOCX 等）之间无缝转换。

1. 环境准备

在开始之前，请确保你的系统已安装以下核心依赖。PDF 转换功能需要额外的 LaTeX 环境支持。

核心依赖

• Pandoc: 文档转换核心引擎。
• UV: Python 包管理工具（用于运行 uvx 命令）。

可选依赖（仅当需要生成 PDF 时）

• TeX Live: PDF 渲染引擎。如果不安装此组件，将无法生成 PDF 文件。

安装命令

macOS (推荐使用 Homebrew):

# 安装 Pandoc
brew install pandoc

# 安装 UV
brew install uv

# 安装 TeX Live (仅用于 PDF 输出)
brew install texlive

Ubuntu/Debian:

# 安装 Pandoc
sudo apt-get install pandoc

# 安装 UV
pip install uv

# 安装 TeX Live (仅用于 PDF 输出)
sudo apt-get install texlive-xetex

Windows:

1. Pandoc: 下载并运行安装包：https://pandoc.org/installing.html
2. UV: 打开 PowerShell 或 CMD 运行 pip install uv
3. TeX Live: 下载并安装 MiKTeX 或 TeX Live：https://miktex.org/ 或 https://tug.org/texlive/

验证安装

在终端执行以下命令确认安装成功：

pandoc --version
uvx --version

2. 安装步骤 (配置 MCP 服务器)

你需要将 mcp-pandoc 配置到你的 MCP 客户端中（以 Claude Desktop 为例）。

配置文件路径

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

配置内容

打开上述配置文件，在 mcpServers 对象中添加以下配置：

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

保存文件后，重启 Claude Desktop 即可生效。

3. 基本使用

配置完成后，你可以直接在对话中请求进行文档转换。mcp-pandoc 支持 Markdown, HTML, TXT, DOCX, PDF, RST, LaTeX, EPUB, IPYNB, ODT 等多种格式的互转。

⚠️ 重要使用规则

1. 完整路径: 对于高级格式（PDF, DOCX, RST, LaTeX, EPUB），必须提供包含文件名和扩展名的完整输出路径（例如 /Users/name/doc.pdf），不能只提供目录。
2. PDF 限制: PDF 仅支持作为输出格式，不支持从 PDF 转换为其他格式。

使用示例

场景 1：将文本内容直接转换为 PDF

“将这段文字转换为 PDF 格式，并保存为 /Users/myname/documents/report.pdf"

场景 2：转换本地文件格式 (Markdown 转 Word)

“将 /Users/myname/notes.md 转换为 DOCX 格式，保存为 /Users/myname/notes.docx"

场景 3：使用参考文档进行样式化转换 (DOCX)

如果你希望生成的 Word 文档遵循特定的样式模板：

1. 首先准备一个参考文档（或使用现有的 .docx 文件）。
2. 发送指令：

“将 input.md 转换为 DOCX 格式，使用 /path/to/template.docx 作为参考样式文档，输出保存为 /path/to/output.docx"

场景 4：简单格式互转 (无需指定输出文件)

对于基础格式（如 Markdown 转 HTML 文本），可以直接在对话框中查看结果：

“将以下内容转换为 HTML 格式：[在此粘贴内容]"