MCP Pandoc

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

正式纳入 模型上下文协议服务器 开源项目。 🎉

概述

用于文档格式转换的模型上下文协议服务器 潘多拉此服务器提供在不同文档格式之间转换内容的工具，同时保留格式和结构。

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

鸣谢：本项目使用 Pandoc Python包 对于文档转换，构成了该项目的基础。

📋 快速参考

潘多克是新来的吗？ 结账 📖 CHEATSHEET.md 为了

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

_非常适合快速查找和快速开始！_

演示

🎥 YouTube上观看

Screenshots

更多即将到来。..

工具

1. convert-contents

- 在支持的格式之间转换内容 - 输入： - contents （string）：要转换的源内容（如果未提供input_file，则需要） - input_file （string）：输入文件的完整路径（如果未提供内容，则需要） - input_format （string）：内容的源格式（默认为markdown） - output_format （string）：目标格式（默认为markdown） - output_file （string）：输出文件的完整路径（pdf、docx、rst、latex、epub格式需要） - reference_doc （string）：用于样式设置的参考文档的路径（支持docx输出格式） - defaults_file （string）：包含转换选项的Pandoc默认文件（YAML）的路径 - filters （array）：转换期间要应用的Pandoc筛选器路径列表 - 支持的输入/输出格式： - 标记语言 - 超文本标记语言 - PDF - 文档 - rst - 胶乳 - 电子书 - 文本 - ipynb - 终端电阻 - 注意：对于高级格式（pdf、docx、rst、latex、epub），需要一个output_file路径

🔧 高级功能

默认文件（YAML配置）

使用默认文件创建格式一致的可重用转换模板：

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

示例用法： "Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf"

Pandoc过滤器

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

示例用法： "Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as 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
  # Download installer from: https://pandoc.org/installing.html

• 验证: pandoc --version

1. UV封装安装

• 必需：安装 uv 套餐（包括 uvx 命令）

• 安装：

  # macOS
  brew install uv

  # Windows/Linux
  pip install uv

• 验证: uvx --version

1. 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/

1. 文件路径要求

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

例子

✅ 正确用法：

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

# 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（请参阅上面的安装命令）

1. 文件转换失败

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

1. 格式转换失败

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

1. 参考文件问题

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

快速启动

通过claude_desktop_config配置文件手动安装

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

a） 仅用于本地开发和对该回购的贡献

Development/Unpublished Servers Configuration

ℹ️ 替换 使用本地克隆的项目路径

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--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

1. 构建包分发：

uv build

这将在 dist/ 目录。

1. 发布到PyPI：

uv publish

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

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

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.

您可以通过以下方式启动MCP检查器 使用此命令：

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

启动后，检查器将显示一个URL，您可以在浏览器中访问该URL以开始调试。

______________________________________________________________________

贡献

我们欢迎为加强mcp pandoc做出贡献！以下是您如何参与其中：

1. 报告问题：发现错误或有功能请求？在我们的 页面。
2. 提交拉取请求：通过创建pull请求来改进代码库或添加功能。

______________________________________________________________________