Mineru MCP Server

将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 Boolean	True	是否启用表格识别
extra_formats	list[str]	["html"]	Mineru应包含的附加导出格式列表，必须包括html
poll_interval	float	3.0	污染任务状态的时间间隔（秒）
max_wait	float	1800.0	单个批次任务的最大等待时间（秒）
rename_assets_flag Boolean	True	是否重命名返回的图像资源并同步更新HTML引用
is_ocr Boolean	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"}
  ]
}

调用示例（FastMCP客户端）

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())

快速验证

1. 准备几个PDF文件放置在目标目录，并确保令牌可用
2. 执行run-mineru-mcp启动服务
3. 使用上述示例或MCP兼容客户端触发convert_pdfs_with_mineru
4. 在output_folder查看生成的HTML和图像资源

常见问题

• 上传失败检查令牌是否有效，网络是否畅通，或者文件是否过大
• 转换超时适当增加max_wait，或减少单批文件数量
• 资源未重命名确认rename_assets_flag设置为True，并确认ZIP文件中存在figure/images等资源文件夹