Docconvert MCP

DocConvert MCP服务器

用于通用文档格式转换的FastMCP服务器。将PDF、Word文档、HTML、Markdown、LaTeX等转换为任何输出格式。

特性

• 通用转换 -在20多种文档格式之间转换
• PDF支持 -使用pdf2docx进行精确的PDF提取，然后使用pandoc
• OCR支持 -从扫描的PDF中提取文本，并保留布局
• GROBID集成 -从学术PDF中提取元数据和参考文献
• 批量处理 -将整个目录转换为混合格式
• 并行处理 -实现真正PDF并行性的子进程隔离
• 递归模式 -处理嵌套文件夹结构
• 格式过滤 -仅转换特定文件类型（例如，仅转换PDF）

建筑

Claude Code
    │
    └── DocConvert MCP Server (this)
            │
            ├── pdf2docx (PDF → DOCX extraction)
            ├── PyMuPDF (OCR with layout preservation)
            ├── GROBID (metadata + references extraction)
            │
            └── pandoc (all other conversions)

支持格式

输入格式

pdf, docx, odt, html, md, tex, latex, rst, epub, rtf, txt, org, mediawiki, textile, asciidoc

输出格式

odt, docx, html, markdown, latex, pdf, epub, rst, asciidoc, rtf, txt, org, mediawiki

安装

先决条件

# Install pandoc
sudo apt install pandoc

设置

git clone https://github.com/jwingnut/docconvert-mcp.git
cd docconvert-mcp
uv venv
source .venv/bin/activate
uv pip install fastmcp pdf2docx

MCP客户端配置

Claude Code CLI

创建或编辑 .mcp.json 在您的项目目录（或更广泛的父目录）中：

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/python",
      "args": ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

然后在中启用服务器 .claude/settings.local.json:

{
  "enabledMcpjsonServers": ["docconvert"]
}

Claude Desktop

添加到您的 claude_desktop_config.json:

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

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/python",
      "args": ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

Codex CLI

添加 ~/.codex/config.toml:

[mcp_servers.docconvert]
command = "/path/to/docconvert-mcp/.venv/bin/python"
args = ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
startup_timeout_sec = 30

Cursor

添加到光标MCP设置（设置→ MCP → 添加服务器）：

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/python",
      "args": ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

Windsurf

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/python",
      "args": ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

Cline / Claude Dev

添加到您的Cline MCP设置中：

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/python",
      "args": ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

Continue IDE Extension

添加到“继续”配置中：

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/python",
      "args": ["/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

Alternative: Using fastmcp run

你也可以通过 fastmcp CLI与 --no-banner 为了抑制输出：

{
  "mcpServers": {
    "docconvert": {
      "command": "/path/to/docconvert-mcp/.venv/bin/fastmcp",
      "args": ["run", "--no-banner", "/path/to/docconvert-mcp/pdf2odt_mcp_server.py"]
    }
  }
}

工具

convert

将文档转换为目标格式。

# Single file: PDF to Markdown
convert(
    input="/path/to/document.pdf",
    output="/path/to/document.md",
    format="markdown"
)

# Single file: PDF to ODT
convert(
    input="/path/to/paper.pdf",
    output="/path/to/paper.odt",
    format="odt"
)

# Directory: Convert all supported files to markdown
convert(
    input="/path/to/docs/",
    output="/path/to/output/",
    format="markdown",
    recursive=True
)

# Directory: Only convert PDFs to ODT
convert(
    input="/path/to/mixed_docs/",
    output="/path/to/odt_output/",
    format="odt",
    filter="pdf",
    recursive=True
)

参数：

并行处理：

并行处理适用于所有文件类型。PDF文件使用子进程隔离来绕过pdf2docx的内部锁定，实现真正的并行性。需要足够的CPU和RAM。

# Parallel PDF conversion (4 workers)
convert(
    input="/path/to/pdfs/",
    output="/path/to/output/",
    format="markdown",
    filter="pdf",
    recursive=True,
    parallel=4  # Each PDF runs in isolated subprocess
)

# Response shows parallel PDF info:
# {"total": 10, "converted": 10, "pdf_files": 10, "pdf_parallel": true, "pdf_workers": 4}

# Convert markdown files in parallel (4 workers)
convert(
    input="/path/to/markdown_docs/",
    output="/path/to/output/",
    format="html",
    filter="md",
    recursive=True,
    parallel=4
)

# Mixed formats: all parallel
convert(
    input="/path/to/mixed_docs/",  # Contains PDFs and markdown
    output="/path/to/output/",
    format="html",
    recursive=True,
    parallel=4
)

# Response shows breakdown:
# {"total": 50, "converted": 50, "pdf_files": 10, "pdf_parallel": true, "pdf_workers": 4, "parallel_workers": 4, "parallel_files": 40}

注： 并行PDF处理需要足够的CPU和RAM。在资源受限的系统上，使用 parallel=1 （默认）用于可靠的顺序处理。

跳过现有文件：

使用 overwrite=False 跳过已存在的文件（对于恢复中断的批处理很有用）：

# Resume an interrupted batch - only convert files not yet done
convert(
    input="/path/to/docs/",
    output="/path/to/output/",
    format="markdown",
    recursive=True,
    overwrite=False  # Skip existing output files
)

# Response includes skipped count:
# {"total": 100, "converted": 25, "skipped": 75, "failed": 0}

formats

列出所有支持的输入和输出格式。

formats()
# Returns:
# {
#   "input_formats": ["asciidoc", "docx", "epub", "htm", "html", ...],
#   "output_formats": ["asciidoc", "docx", "epub", "html", "latex", ...],
#   "note": "PDF input uses pdf2docx then pandoc..."
# }

list_convertible

按格式分组，列出路径中的可转换文件。

list_convertible("/path/to/docs/", recursive=True)
# Returns:
# {
#   "success": True,
#   "count": 15,
#   "by_format": {
#     ".pdf": ["file1.pdf", "file2.pdf"],
#     ".docx": ["report.docx"],
#     ".md": ["notes.md", "readme.md"]
#   }
# }

用例

学术写作

转换期刊指南和示例论文以便于参考：

# Convert journal author guidelines
convert(
    input="/path/to/author_guidelines.pdf",
    output="/path/to/guidelines.md",
    format="markdown"
)

# Convert example papers to study structure
convert(
    input="/path/to/example_paper.pdf",
    output="/path/to/example.md",
    format="markdown"
)

文档迁移

批量转换旧文档：

# Convert all Word docs to ODT
convert(
    input="/path/to/word_docs/",
    output="/path/to/odt_docs/",
    format="odt",
    filter="docx",
    recursive=True
)

内容提取

从PDF中提取文本进行分析：

# Convert PDFs to plain text
convert(
    input="/path/to/pdfs/",
    output="/path/to/text/",
    format="txt",
    filter="pdf"
)

Web发布

将文档转换为HTML：

# Markdown to HTML
convert(
    input="/path/to/docs/",
    output="/path/to/html/",
    format="html",
    filter="md",
    recursive=True
)

整合

与其他MCP服务器协同工作：

• LibreOffice MCP -编辑转换后的文档
• Zotero MCP -为转换后的内容添加引用

工作流示例

# 1. Convert journal guidelines
convert(input="guidelines.pdf", output="guidelines.md", format="markdown")

# 2. Read guidelines
Read("guidelines.md")

# 3. Create document in LibreOffice
document(action="create", doc_type="writer")

# 4. Write content following guidelines
text(action="insert", content="...")

# 5. Add citations from Zotero
search_zotero("topic")
text(action="insert", content="{  | (Author, 2020) |  |  |zu:LIB:KEY}")

# 6. Save
save(action="save", file_path="paper.odt")

技术说明

PDF转换

PDF转换分为两个阶段：

1. pdf2docx 将内容提取到DOCX（保留布局、表格、图像）
2. 潘多克。 将DOCX转换为目标格式

对于大多数文档，这比直接PDF解析产生更好的结果。

其他格式

所有非PDF转换都直接使用pandoc，它处理：

• 文档结构（标题、列表、表格）
• 基本格式
• 交叉引用
• 引文（某些格式）

并行PDF处理

PDF并行使用子进程隔离：每个PDF转换都在一个完全独立的Python进程中运行。这绕过了pdf2docx的内部锁定，该锁定阻止了基于线程的并行性。

• 每个子进程：约100-200MB RAM+CPU使用率
• 4个并行工作器：~400-800MB RAM，4个CPU核
• 8个并行工作器：~800MB-1.6GB RAM，8个CPU核

用于扫描PDF的OCR

标准OCR(ocr=True) -保留表格和布局（推荐）：

# Best quality - preserves tables and structure
convert(
    input="/path/to/scanned.pdf",
    output="/path/to/output.md",
    format="markdown",
    ocr=True
)

# Batch OCR conversion
convert(
    input="/path/to/scanned_docs/",
    output="/path/to/output/",
    format="markdown",
    filter="pdf",
    ocr=True,
    recursive=True
)

快速OCR(ocr=True, ocr_fast=True) -更简单，失去布局：

convert(
    input="/path/to/scanned.pdf",
    output="/path/to/output.txt",
    format="txt",
    ocr=True,
    ocr_fast=True
)

独立OCR -创建可搜索的PDF：

ocr_document("/path/to/scanned.pdf", "/path/to/searchable.pdf")

OCR要求：

# Standard OCR (recommended)
pip install pymupdf4llm

# Fast OCR (optional)
pip install ocrmypdf
sudo apt install tesseract-ocr

GROBID学术PDF

使用GROBID从学术文档中提取结构化元数据和参考文献：

# Extract metadata (title, authors, abstract, DOI, etc.)
extract_metadata("/path/to/paper.pdf")
# Returns: {title, authors, abstract, keywords, date, doi, affiliations}

# Extract bibliography/references
extract_references("/path/to/paper.pdf")
# Returns: [{title, authors, year, journal, volume, pages, doi}, ...]

# Extract full document structure
extract_fulltext("/path/to/paper.pdf")
# Returns: metadata + all references

# Save as TEI XML
extract_fulltext("/path/to/paper.pdf", "/path/to/paper.tei.xml")

GROBID要求：

# Start GROBID server (Docker)
docker run -d --name grobid -p 8070:8070 lfoppiano/grobid:0.8.0

# Install client
pip install grobid-client-python

# Optional: Set custom server URL
export GROBID_SERVER=http://your-server:8070

局限性

• 复杂的PDF布局可能无法完美转换
• 转换过程中可能会丢失某些格式
• 并行PDF处理需要足够的系统资源
• OCR质量取决于扫描质量和Tesseract的功能
• GROBID需要一个正在运行的服务器（本地或远程）

文件

pdf2odt-mcp/
├── pdf2odt_mcp_server.py  # MCP server
├── .venv/                  # Virtual environment
├── .gitignore
└── README.md

许可证

麻省理工学院