⚙

文档格式转换服务器

一个基于Pandoc的文档格式转换服务器，支持多种文档格式之间的转换，包括Markdown、HTML、PDF、DOCX等。

作者 By vivekVells

本地部署文档转换格式转换

GitHub

# mcp-pandoc：文档转换mcp服务器> 正式纳入模型上下文协议服务器开源项目。 🎉

概述

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

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

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

📋 快速参考

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

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

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

演示

🎥 YouTube上观看

Screenshots Screenshot 2024-12-26 at 3 33 54 PM Screenshot 2024-12-26 at 3 38 24 PM Screenshot 2024-12-26 at 3 40 51 PM Screenshot 2024-12-26 at 3 41 20 PM Screenshot 2024-12-26 at 3 50 27 PM

更多即将到来。…

工具

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配置）

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

YAML``` 1 2 3 4 5 6 7 8# 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**


## 📊 支持的格式和转换


### 双向转换矩阵


|发件人|收件人| MD | HTML | TXT | DOCX | PDF | RST | LaTeX | EPUB | IPYNB | ODT|
| ------------ | — | ---- | — | ---- | — | — | ----- | ---- | ----- | — |
| **降价** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **超文本标记语言** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **文本** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **文档** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **RST** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **乳胶** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **电子版** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **IPYNB** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |
| **海洋数据发射机** | ✅  | ✅   | ✅  | ✅   | ✅  | ✅  | ✅    | ✅   | ✅    | ✅  |


### 关于PDF支持的说明


此工具使用 `pandoc` 用于转换，它允许从上面列出的格式生成PDF文件。但是，转换 *从* 不支持将PDF转换为其他格式。因此，PDF应被视为 **仅输出** 格式。


### 格式类别


| 类别 | 格式 | 要求 |
| --- | --- | --- |
| **基础** | MD、HTML、TXT、IPYNB、ODT | 无 |
| **高级** | DOCX、PDF、RST、LaTeX、EPUB | 必须指定 `output_file` 路径 |
| **称** | DOCX与参考文档 | 自定义模板支持⭐ |


### 按格式列出的要求


- **PDF（.PDF）** -需要TeX Live安装
- **DOCX（.DOCX）** -支持通过参考文档自定义样式
- **所有其他** -无额外要求


注意：对于高级格式：


1. 需要包含文件名和扩展名的完整文件路径
2. **PDF转换需要安装TeX Live** （请参阅关键要求部分->对于macOS： `brew install texlive`)
3. 未指定输出路径时：

- 基本格式：在聊天中显示转换后的内容
- 高级格式：可以保存在系统临时目录（Unix系统上的/tmp/）中


## 使用和配置


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


使用已发布的


BASH```
1
2
3
4
5
6
7
8{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

💡 快速开始：参见 CHEATSHEET.md 用于复制粘贴示例和常见工作流。

⚠️ 重要提示

关键要求

Pandoc安装

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

BASH``` 1 2 3 4 5 6# 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` 命令）
- 安装：


BASH```
1
2
3
4# macOS
brew install uv
# Windows/Linux
pip install uv

验证: uvx --version

PDF转换先决条件： 仅当您需要转换和保存pdf时才需要

在尝试PDF转换之前，必须安装TeX Live
安装命令：

BASH``` 1 2 3 4 5 6 7# 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. **文件路径要求**


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


#### 例子


✅ 正确用法：


BASH```
1
2
3
4
5
6
7
8
9# 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"

❌ 用法不正确：

BASH``` 1 2 3 4 5 6# 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、乳胶、epub
4. **参考文件问题**


- 错误：“找不到参考文档”
- 解决方案：确保参考文档路径存在且可访问
- 注意：参考文档仅适用于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
ℹ️ 替换  使用本地克隆的项目路径


BASH```
1
2
3
4
5
6
7
8
9
10
11"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

b）已发布的服务器配置-消费者应使用此配置

BASH``` 1 2 3 4 5 6 7 8”mcpServers”: { “mcp-pandoc”: { “command”: “uvx”, “args”: [ “mcp-pandoc” ] } }



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


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


## 发展


### 测试


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


BASH```
1uv run pytest tests/test_conversions.py

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

建筑与出版

准备分发包裹：

同步依赖关系并更新锁文件：

BASH``` 1uv sync


1. 构建包分发：


BASH```
1uv build

这将在 dist/ 目录。

发布到PyPI：

BASH``` 1uv publish


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


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


### 调试


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


您可以通过以下方式启动MCP检查器 [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) 使用此命令：


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

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

贡献

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

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