内容
# mineru-docparse-mcp
MCP 服务器，可将 Word / PDF / PPT / Excel 等文件转换为 Markdown， 由 [MinerU DocParse API](https://github.com/opendatalab/MinerU) 提供支持。
> 本项目是一个协议包装器 - 它本身并不解析文档。您需要一个正在运行的 MinerU DocParse 服务，默认为 `http://localhost:8000`。请参阅 [MinerU 仓库](https://github.com/opendatalab/MinerU) 获取部署说明。
## 安装
```bash
pip install mineru-docparse-mcp
```
## 使用 Claude 代码设置
输出目录是一个服务器端设置（不是每个请求的独立参数），因此必须提前配置 `MINERU_OUTPUT_DIR`:
```json
{
"mcpServers": {
"mineru": {
"command": "uvx",
"args": ["mineru-docparse-mcp"],
"env": {
"MINERU_API_URL": "http://localhost:8000",
"MINERU_OUTPUT_DIR": "/Users/yourname/Documents/mineru-output"
}
}
}
}
```
配置完成后，Claude 将自动调用以下工具。所有解析结果都保存到 `MINERU_OUTPUT_DIR`。
## 工具列表
| 工具 | 描述 |
|---|---|
| `mineru_parse_document` | 将 PDF/Word/PPT/Excel 转换为 Markdown，保存到磁盘 |
| `mineru_health_check` | 检查 MinerU 服务健康状态 |
**输出格式**: 结果与 MinerU 返回的内容完全一致。当 `response_format_zip=true`（默认值）时，输出以 `.zip` 格式保存；当 `false` 时，以 `.json` 格式保存。文件名与源文件名匹配 - 如果文件名已存在，则追加时间戳以避免覆盖。
## API 参数
`mineru_parse_document` 镜像 MinerU 的 `/file_parse` 端点:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `file_path` | 字符串 | 必需 | 本地文档路径（绝对或相对） |
| `backend` | 枚举 | `hybrid-engine` | 解析后端，参见下面的“后端选项” |
| `lang_list` | 字符串数组 | `["ch"]` | OCR 语言列表，仅适用于 `pipeline` 后端 |
| `effort` | `medium` | `high` | 仅适用于 `hybrid` 后端。`medium`: 速度较快，无图表分析；`high`: 精度较高，包含图表分析，速度较慢 |
| `parse_method` | `auto` | `txt` | `ocr` | `auto` | PDF 解析方法，适用于 `pipeline`/`hybrid`：自动检测 / 文本提取 / OCR |
| `formula_enable` | 布尔值 | `true` | 启用公式解析（LaTeX） |
| `table_enable` | 布尔值 | `true` | 启用表格解析 |
| `image_analysis` | 布尔值 | `true` | 启用图像/图表分析（仅适用于 VLM/hybrid 后端） |
| `server_url` | 字符串 | `null` | OpenAI 兼容服务器 URL，适用于 `*-http-client` 后端 |
| `return_md` | 布尔值 | `true` | 在响应中包含 Markdown 内容 |
| `return_middle_json` | 布尔值 | `false` | 在响应中包含中间 JSON |
| `return_model_output` | 布尔值 | `false` | 在响应中包含原始模型输出 JSON |
| `return_content_list` | 布尔值 | `false` | 在响应中包含内容列表 JSON |
| `return_images` | 布尔值 | `false` | 在响应中包含提取的图像 |
| `response_format_zip` | 布尔值 | **`true`** （本项目的默认值；API 默认值为 `false`） | 返回结果为 ZIP（`false` 返回 JSON） |
| `return_original_file` | 布尔值 | `false` | 在 ZIP 中包含已处理的原始文件（仅当 `response_format_zip=true` 时） |
| `client_side_output_generation` | 布尔值 | `false` | 将最终 Markdown/内容列表生成延迟到客户端 |
| `start_page_id` | 整数 | `0` | 起始页（0 索引） |
| `end_page_id` | 整数 | `99999` | 结束页（0 索引） |
### 后端选项
| 值 | 描述 |
|---|---|
| `pipeline` | 通用、多语言、无幻觉 |
| `vlm-engine` | 本地计算、高精度、仅限中文/英文 |
| `vlm-http-client` | 远程计算（OpenAI 兼容）、高精度、仅限中文/英文 |
| `hybrid-engine` （默认）| 本地计算、混合解析、多语言、可通过 `effort` 调整 |
| `hybrid-http-client` | 主要远程计算 + 轻量本地计算、混合解析、多语言 |
### 语言选项（`lang_list`）
`ch` （中文/英文/日文/繁体/拉丁文）、`ch_server`、`korean`、`ta` （泰米尔文）、`te` （泰卢固文）、`ka` （卡纳达文）、`th` （泰文）、`el` （希腊文）、`arabic`、`east_slavic`、`cyrillic`、`devanagari`。仅适用于 `pipeline` 后端；其他后端忽略。
## 服务器配置（环境变量）
这些是服务器启动设置 - 在 MCP 配置的 `env` 字段中配置，而不是作为每个请求的独立参数。
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MINERU_API_URL` | `http://localhost:8000` | MinerU 服务 URL |
| `MINERU_OUTPUT_DIR` | 无（必需） | 解析结果目录（绝对或相对路径） |
| `MINERU_API_TIMEOUT` | `600` | 请求超时（秒）- 对于大文件，增加超时时间 |
| `MCP_TRANSPORT` | `stdio` | 传输模式：`stdio` （本地子进程）或 `streamable-http` （远程） |
| `MCP_HOST` | `127.0.0.1` | 监听地址（仅 HTTP 模式）；设置为 `0.0.0.0` 以公开暴露 |
| `MCP_PORT` | `8001` | 监听端口（仅 HTTP 模式） |
## 远程部署（可选）
要在专用机器上运行 MCP 服务器，并允许多个客户端访问，请使用 HTTP 模式:
```bash
MCP_TRANSPORT=streamable-http MCP_PORT=8001 MINERU_OUTPUT_DIR=/data/mineru-output uvx mineru-docparse-mcp
```
客户端通过 URL 连接:
```json
{
"mcpServers": {
"mineru": {
"type": "streamableHttp",
"url": "http://<服务器地址>:8001/mcp"
}
}
}
```
省略 `MCP_TRANSPORT` 默认使用本地 stdio 模式（上面的“使用 Claude 代码设置”流程），这足以满足个人使用。
## 常见问题
**“MINERU_OUTPUT_DIR 环境变量未配置”** - 这是一个必需的服务器设置，而不是 API 参数。在 MCP 配置的 `env` 字段中设置它，然后重启 MCP 连接。
**“无法连接到 MinerU 服务”** - 验证 `MINERU_API_URL` 是否可访问：`curl $MINERU_API_URL/health`。在 stdio 模式下，环境变量必须在 MCP 配置的 `env` 字段中设置；shell `export` 不起作用。
**大文件超时** - 增加 `MINERU_API_TIMEOUT` 或缩小 `start_page_id`/`end_page_id` 范围，以分批解析。
**想要 JSON 而不是 ZIP** - 将 `response_format_zip` 设置为 `false`；结果将保存为 `.json` 而不是 `.zip`。
## License
MIT
