MCP 服务器

Mineru MCP Server

Enables batch conversion of PDF files to HTML format using Mineru's official PDF parsing API. Supports automatic file scanning, customizable parsing parameters, and organized output with renamed image assets.

README

Mineru MCP 服务端

将 Mineru 官方 PDF 解析能力封装为 FastMCP 服务，便于任意支持 MCP 协议的客户端调用，实现批量 PDF 转 HTML（含图片资源整理与命名）。

功能亮点

自动扫描指定目录下的 PDF 文件并批量上传至 Mineru
支持自定义语言、表格识别开关、额外输出格式等参数
下载 Mineru 返回的 ZIP 结果，自动整理 HTML 与图片资源，支持按文件名规则重命名
通过 FastMCP 暴露 convert_pdfs_with_mineru 工具，可直接被主流大模型代理调用

环境要求

Python 3.10 及以上版本
可访问 https://mineru.net 的网络环境
Mineru API Token（可通过参数或环境变量 MINERU_API_TOKEN 提供）

安装步骤

cd main/mineru_mcp_project
pip install -e .

配置 API Token

# PowerShell 示例
$env:MINERU_API_TOKEN = "你的 Mineru Token"

也可在调用工具时通过 api_token 参数显式传入。

启动服务

run-mineru-mcp

服务默认监听本地 http://127.0.0.1:4399/mcp/。

工具：convert_pdfs_with_mineru

参数	类型	默认值	说明
`pdf_folder`	str	–	PDF 文件所在目录（必填）
`output_folder`	str	–	转换结果输出目录（必填）
`api_token`	str	`None`	可选，若未提供则读取环境变量 `MINERU_API_TOKEN`
`language`	str	`"ch"`	Mineru 解析语言参数
`enable_table`	bool	`True`	是否启用表格识别
`extra_formats`	list[str]	`["html"]`	Mineru 额外导出格式列表，应包含 `html`
`poll_interval`	float	`3.0`	轮询任务状态的时间间隔（秒）
`max_wait`	float	`1800.0`	单批任务的最大等待时间（秒）
`rename_assets_flag`	bool	`True`	是否对返回的图片资源重命名并同步更新 HTML 引用
`is_ocr`	bool	`True`	上传 Mineru 时的 OCR 开关

返回结构示例

{
  "pdf_total": 12,
  "uploaded": 12,
  "completed": 12,
  "output_directory": "D:/Mineru/output",
  "details": [
    {"file": "sample.pdf", "stage": "upload", "status": "success", "message": "上传成功"},
    {"file": "sample.pdf", "stage": "download", "status": "success", "message": "已保存 sample.html"}
  ]
}

调用 Demo（FastMCP Client）

import asyncio
from fastmcp import Client

client = Client("http://127.0.0.1:4399/mcp/")

async def main():
    async with client:
        result = await client.call_tool(
            "convert_pdfs_with_mineru",
            {
                "pdf_folder": r"D:\\Docs\\pdf",
                "output_folder": r"D:\\Docs\\html",
                "poll_interval": 5.0,
                "max_wait": 3600.0
            }
        )
        print(result.data)

if __name__ == "__main__":
    asyncio.run(main())

快速验证

准备若干 PDF 放入目标目录，并确保 Token 可用
执行 run-mineru-mcp 启动服务
使用上述 Demo 或 MCP 兼容客户端触发 convert_pdfs_with_mineru
在 output_folder 查看生成的 HTML 及图片资源

常见问题

上传失败：检查 Token 是否有效、网络是否通畅，或文件是否过大
转换超时：适当增大 max_wait，或缩小单次批量文件数量
资源未重命名：将 rename_assets_flag 设为 True，并确认 ZIP 内存在 figure/images 等资源文件夹