已正式纳入 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: "研究团队"

示例用法："使用默认文件 academic-paper.yaml 将 paper.md 转换为 PDF 并保存为 paper.pdf"

Pandoc 过滤器

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

示例用法："使用过滤器 ['/path/to/mermaid-filter.py'] 将 docs.md 转换为 HTML 并保存为 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
"将此文本转换为 PDF 并保存为 /path/to/document.pdf"

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

使用参考文档模板转换为DOCX

"使用template.docx作为参考，将input.md转换为DOCX并保存为output.docx"

分步参考文档工作流程

"首先创建一个参考文档：pandoc -o custom-reference.docx --print-default-data-file reference.docx"，或者如果你已经有一个参考文档，直接使用它 "然后使用自定义样式进行转换：使用/path/to/custom-reference.docx作为参考，将此文本转换为DOCX并保存为/path/to/styled-output.docx"

❌ 错误用法：

```bash
# 缺少文件名和扩展名
"将此保存为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

快速开始

安装

选项1：通过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"
    ]
  }
}

选项2：通过Smithery自动安装已发布服务器配置

运行以下bash命令，通过Smithery自动为Claude Desktop安装已发布的mcp-pandoc pypi：

npx -y @smithery/cli install mcp-pandoc --client claude

• 如果遇到任何问题，请直接使用上面的"已发布服务器配置"，而不是此cli。

注意：要使用本地配置的mcp-pandoc，请按照上面的"开发/未发布服务器配置"步骤操作。

开发

测试

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

uv run pytest tests/test_conversions.py

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

构建与发布

要准备分发包：

1. 同步依赖并更新lockfile：

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. 提交拉取请求：通过创建拉取请求来改进代码库或添加功能。