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

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

概述

这是一个基于文档转换工具pandoc实现的模型上下文协议(MCP)服务器，用于文档格式转换。该服务器提供在不同文档格式间转换内容的工具，同时保持格式和结构的完整性。

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

致谢：本项目使用Pandoc Python包作为文档转换的基础。

演示

🎥 在YouTube观看

截图

更多内容即将推出...

工具

convert-contents
- 在支持的格式之间转换内容
- 输入参数：
  - contents (字符串)：要转换的源内容（如果未提供input_file则必须提供）
  - input_file (字符串)：输入文件的完整路径（如果未提供contents则必须提供）
  - input_format (字符串)：内容的源格式（默认为markdown）
  - output_format (字符串)：目标格式（默认为markdown）
  - output_file (字符串)：输出文件的完整路径（对于pdf、docx、rst、latex、epub格式必须提供）
- 支持的输入/输出格式：
  - markdown
  - html
  - pdf
  - docx
  - rst
  - latex
  - epub
  - txt
- 注意：对于高级格式（pdf、docx、rst、latex、epub），必须提供output_file路径

支持的格式

当前支持的格式：

基础格式（可直接转换）：

纯文本 (.txt)
Markdown (.md)
HTML (.html)

高级格式（需要完整文件路径）：

PDF (.pdf) - 需要安装TeX Live
DOCX (.docx)
RST (.rst)
LaTeX (.tex)
EPUB (.epub)

注意：对于高级格式：

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

使用与配置

注意：请确保完成下面"关键要求"部分提到的所需包的安装。

使用已发布的版本：

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

⚠️ 重要注意事项

关键要求

Pandoc安装

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

安装方法：

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
# 从以下网址下载安装程序：https://pandoc.org/installing.html

验证：pandoc --version

UV包安装
- 必需：安装uv包（包含uvx命令）
- 安装方法：
```
# macOS
brew install uv

# Windows/Linux
pip install uv
```
- 验证：uvx --version

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/

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

示例

✅ 正确用法：

# 将内容转换为PDF
"将此文本转换为PDF并保存为/path/to/document.pdf"

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

❌ 错误用法：

# 缺少文件名和扩展名
"将此保存为PDF到/documents/"

# 缺少完整路径
"将此转换为PDF"

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

常见问题及解决方案

PDF转换失败
- 错误："xelatex未找到"
- 解决方案：先安装TeX Live（参见上面的安装命令）
文件转换失败
- 错误："无效的文件路径"
- 解决方案：提供包含文件名和扩展名的完整路径
- 示例：/path/to/document.pdf 而不仅仅是 /path/to/
格式转换失败
- 错误："不支持的格式"
- 解决方案：仅使用支持的格式：
  - 基础格式：txt、html、markdown
  - 高级格式：pdf、docx、rst、latex、epub

快速开始

安装

选项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 sync

构建包分发：

uv build

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

发布到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的贡献！以下是你可以参与的方式：

报告问题：发现错误或有功能请求？在我们的GitHub Issues页面上打开一个问题。
提交拉取请求：通过创建拉取请求来改进代码库或添加功能。