{"id":45857958,"url":"https://github.com/avatarganymede/mineru-mcp","last_synced_at":"2026-02-27T05:00:54.604Z","repository":{"id":340373786,"uuid":"1162376212","full_name":"AvatarGanymede/MinerU-MCP","owner":"AvatarGanymede","description":"MCP server to convert PDF/Word/PPT/Image/HTML to Markdown via MinerU API.","archived":false,"fork":false,"pushed_at":"2026-02-24T14:04:47.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T18:52:47.415Z","etag":null,"topics":["agent-skill","markdownconversion","mcp-server","mineru","pdf-to-markdown"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AvatarGanymede.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T07:23:11.000Z","updated_at":"2026-02-24T14:04:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AvatarGanymede/MinerU-MCP","commit_stats":null,"previous_names":["avatarganymede/mineru-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AvatarGanymede/MinerU-MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvatarGanymede%2FMinerU-MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvatarGanymede%2FMinerU-MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvatarGanymede%2FMinerU-MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvatarGanymede%2FMinerU-MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AvatarGanymede","download_url":"https://codeload.github.com/AvatarGanymede/MinerU-MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AvatarGanymede%2FMinerU-MCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29885799,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","markdownconversion","mcp-server","mineru","pdf-to-markdown"],"created_at":"2026-02-27T05:00:47.231Z","updated_at":"2026-02-27T05:00:54.585Z","avatar_url":"https://github.com/AvatarGanymede.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MinerU Document to Markdown MCP Server\n\n[English](README_EN.md) | 中文\n\n一个 Model Context Protocol (MCP) 服务器，用于通过 MinerU API 将多种格式文档转换为 Markdown 格式。支持 URL 和本地文件两种输入方式。\n\n## 功能特点\n\n- 🔄 使用 Python requests 调用 MinerU API\n- 📄 支持多种格式：PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML\n- 📁 支持本地文件自动上传解析\n- 🔍 支持 OCR、公式识别、表格识别\n- 🧠 智能参数自动配置（根据文件类型自动选择模型和参数）\n- 📦 大文件智能拆分（\u003e200MB 自动物理拆分，\u003e600 页自动使用 page_ranges）\n- ⚡ 提供完整的转换工作流（提交任务 → 轮询状态 → 获取结果）\n\n## 安装\n\n### 1. 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. 获取 MinerU API Token\n\n访问 [https://mineru.net](https://mineru.net) 注册并申请 API Token。\n\n### 3. 配置 MCP 客户端\n\n#### 方式一：uvx 启动（推荐，无需手动安装依赖）\n\n安装 [uv](https://docs.astral.sh/uv/) 后，可直接通过 `uvx` 运行，无需 `pip install`：\n\n```bash\nuvx mineru-converter-mcp-server stdio\n```\n\n编辑 Claude Desktop 或 Cursor MCP 配置文件：\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json` 或 Cursor 设置中的 MCP 配置\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--with\", \"mineru-converter-mcp-server\", \"python\", \"-m\", \"mineru_mcp\", \"stdio\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your_mineru_api_token\"\n      }\n    }\n  }\n}\n```\n\n\u003e **说明**：使用 `-m mineru_mcp` 模块方式启动，可规避 Windows 下 uvx console script 的兼容问题。开发阶段可从源码安装：`uv pip install -e .` 后使用 `mineru-converter-mcp-server stdio`。\n\n#### 方式二：Python 版（功能完整，支持本地文件和大文件拆分）\n\n需先安装依赖：`pip install -r requirements.txt`\n\n编辑 Claude Desktop 配置文件：\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"python\",\n      \"args\": [\"src/mineru_mcp/server.py\"],\n      \"cwd\": \"C:/path/to/MinerU-MCP\",\n      \"env\": {\n        \"MINERU_API_KEY\": \"your_mineru_api_token\"\n      }\n    }\n  }\n}\n```\n\n\u003e 将 `C:/path/to/MinerU-MCP` 替换为项目实际路径。`cwd` 确保从项目根目录运行。\n\n#### 方式三：TypeScript 版（适用于 Smithery 部署和本地开发）\n\n需要先安装 Node.js 20+ 和项目依赖：\n\n```bash\nnpm install\n```\n\n在项目根目录创建 `.mcp.json`（Claude Code）或编辑 `claude_desktop_config.json`（Claude Desktop）：\n\n**macOS / Linux:**\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"src/main.ts\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your_mineru_api_token\"\n      }\n    }\n  }\n}\n```\n\n**Windows:**\n\n```json\n{\n  \"mcpServers\": {\n    \"mineru\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"tsx\", \"src/main.ts\"],\n      \"env\": {\n        \"MINERU_API_KEY\": \"your_mineru_api_token\"\n      }\n    }\n  }\n}\n```\n\n\u003e **注意**：TypeScript 版仅支持 URL 输入，不支持本地文件上传和大文件拆分。如需这些功能请使用 Python 版。\n\n**本地 HTTP 服务**（可选）：`npm run start:http` 或 `MINERU_API_KEY=xxx npx tsx src/server-http.ts`，默认监听 10000 端口，暴露 `/mcp` 和 `/.well-known/mcp-config`。\n\n两种方式均需将 `your_mineru_api_token` 替换为你的 MinerU API Token（在 [https://mineru.net/apiManage/token](https://mineru.net/apiManage/token) 申请）。\n\n### 部署到 Render（Deploy via URL，免费）\n\n使用 [Render](https://render.com) 将 TypeScript 版 MCP 部署为公开 HTTPS 服务，然后在 Smithery 选择「Deploy via URL」即可免费分发。**无需 smithery dev**，自建 HTTP 服务即可运行。\n\n1. **Fork 并推送**：确保本仓库代码已推送到 GitHub\n2. **创建 Blueprint**：打开 [Render Dashboard](https://dashboard.render.com/) → New → Blueprint\n3. **连接仓库**：选择 `MinerU-MCP` 仓库，Render 会自动读取根目录的 `render.yaml`\n4. **部署**：点击 Create / Apply，等待构建完成\n5. **获取 URL**：部署完成后会得到 `https://mineru-mcp.onrender.com` 之类的 HTTPS 地址\n6. **登记到 Smithery**：\n   - **网页**：在 [Smithery New Server](https://smithery.ai/servers/new) 选择 External MCP / Deploy via URL，填入上述 URL（会有 config schema 警告，可忽略；用户在 Add Parameter 中手动填 `mineruApiKey`）\n   - **CLI（推荐，消除警告）**：`smithery auth login` 登录后执行：\n     ```bash\n     smithery mcp publish \"https://你的Render地址/mcp\" -n @你的命名空间/mineru-mcp --config-schema '{\"type\":\"object\",\"properties\":{\"mineruApiKey\":{\"type\":\"string\",\"title\":\"MinerU API Key\",\"description\":\"Your MinerU API Key (obtain from https://mineru.net/apiManage/token)\",\"x-from\":{\"header\":\"x-mineru-api-key\"}}}}'\n     ```\n\n\u003e **Smithery Deploy via URL**：不设置 `MINERU_API_KEY`，每个用户会在 Smithery 添加 MCP 时填写自己的 API Key。\n\u003e\n\u003e **自托管单租户**：在 Render Environment 中设置 `MINERU_API_KEY`，则所有请求共用该 Key。\n\n## 支持的文件格式\n\n| 格式 | 扩展名 | 自动配置 |\n|------|--------|---------|\n| PDF | .pdf | 默认使用 vlm 模型 |\n| Word | .doc, .docx | 默认使用 vlm 模型 |\n| PowerPoint | .ppt, .pptx | 默认使用 vlm 模型 |\n| 图片 | .png, .jpg, .jpeg | 自动开启 OCR |\n| 网页 | .html | 自动使用 MinerU-HTML 模型 |\n\n## 大文件处理\n\n服务器自动处理超大文件，无需手动干预：\n\n- **文件 \u003e200MB（仅 PDF）**：自动物理拆分为多个小文件，分别处理后返回结果\n- **文件 \u003e600 页（仅 PDF）**：自动使用 page_ranges 参数分段处理\n- **拆分算法**：同时考虑文件大小（180MB/片）和页数（600页/片）双重约束，取较大值确保每个分片同时满足两个限制\n\n## 使用方法\n\n### 工具 1: create_parse_task\n\n创建一个文档解析任务。支持 URL 或本地文件路径，本地文件会自动上传。\n\n**参数：**\n- `url` (必需): 文档的 URL 或本地文件路径（支持 PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML）\n- `model_version` (可选): 模型版本，根据文件类型自动选择（vlm / pipeline / MinerU-HTML）\n- `is_ocr` (可选): 是否启用 OCR（图片格式自动启用），默认 `false`\n- `enable_formula` (可选): 是否启用公式识别，默认 `true`\n- `enable_table` (可选): 是否启用表格识别，默认 `true`\n\n**返回值：**\n- URL 输入：返回 `task_id`\n- 本地文件输入：返回 `batch_id`\n- 大文件拆分：返回 `batch_ids` 列表\n\n**示例：**\n```\n# PDF 文件\n请解析这个 PDF：https://example.com/report.pdf\n\n# Word 文档\n请解析本地 Word 文档：C:/Documents/report.docx\n\n# PowerPoint 文件\n请解析本地 PPT：C:/Documents/slides.pptx\n\n# 图片（自动 OCR）\n请解析这张图片：C:/Documents/scan.png\n\n# HTML 网页\n请解析本地 HTML：C:/Documents/page.html\n```\n\n### 工具 2: get_task_status\n\n查询任务状态。支持通过 `task_id`（URL 解析）或 `batch_id`（本地文件上传）查询。\n\n**参数：**\n- `task_id` (可选): 任务 ID（URL 方式创建的任务）\n- `batch_id` (可选): 批量任务 ID（本地文件上传创建的任务）\n\n\u003e 两个参数至少提供一个。\n\n### 工具 3: download_result\n\n下载解析结果 zip 文件。\n\n**参数：**\n- `zip_url` (必需): 结果文件的 URL\n- `output_path` (必需): 本地保存路径\n\n### 工具 4: convert_to_markdown (推荐)\n\n完整的转换工作流，自动提交任务、等待完成并下载结果。支持所有格式的 URL 或本地文件路径。\n\n**参数：**\n- `url` (必需): 文档的 URL 或本地文件路径\n- `output_path` (必需): 结果 zip 文件的本地保存路径\n- `model_version` (可选): 模型版本（自动检测），默认 `vlm`\n- `max_wait_seconds` (可选): 最大等待时间（秒），默认 300\n- `poll_interval` (可选): 轮询间隔（秒），默认 10\n\n**示例：**\n```\n# 转换 PDF\n帮我把这个 PDF 转成 Markdown：\nurl: C:/Documents/report.pdf\noutput_path: C:/output/result.zip\n\n# 转换 Word 文档\n帮我把这个 Word 文档转成 Markdown：\nurl: C:/Documents/report.docx\noutput_path: C:/output/result.zip\n\n# 转换 PPT\n帮我把这个 PPT 转成 Markdown：\nurl: C:/Documents/slides.pptx\noutput_path: C:/output/result.zip\n```\n\n\u003e 注：`convert_pdf_to_markdown` 仍可使用（向后兼容），功能与 `convert_to_markdown` 完全相同。\n\n## Claude Code Skill 快捷用法\n\n本项目提供了 `/convert-to-markdown` skill，可在 Claude Code 中通过斜杠命令快速调用文档转 Markdown 功能。\n\n### 基本用法\n\n```\n/convert-to-markdown \u003c文档路径或URL\u003e [指令]\n```\n\n### 示例\n\n```bash\n# 转换 PDF\n/convert-to-markdown C:/Documents/report.pdf 分析并总结这个文档内容\n\n# 转换 Word 文档\n/convert-to-markdown C:/Documents/report.docx 提取文档要点\n\n# 转换 PPT\n/convert-to-markdown C:/Documents/slides.pptx\n\n# 转换图片\n/convert-to-markdown C:/Documents/scan.png 识别图片中的文字\n```\n\n### 说明\n\n- 支持本地文件路径和 HTTP(S) URL 两种输入\n- 支持 PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML 格式\n- 未指定输出路径时，默认保存到 `./temp/\u003c文件名\u003e.zip`\n- 转换完成后自动解压 zip 并读取 Markdown 内容\n- 可附加自然语言指令，让 Claude 对转换结果进行分析、总结或回答问题\n\n## API 限制\n\n根据 MinerU API 文档：\n\n- 单个文件不超过 200MB（PDF 超过此限制会自动拆分）\n- 文件页数不超过 600 页（超过此限制会自动使用 page_ranges）\n- 每账号每天有 2000 页高优先级额度\n- 不支持 GitHub、AWS 等国外 URL（网络限制）\n\n## 输出格式\n\n转换完成后，会得到一个包含以下内容的 zip 文件：\n\n- **Markdown 文件**: 提取的文档内容\n- **JSON 文件**: 结构化数据\n- **可选格式**: 如果指定了 `extra_formats`，还可能包含 DOCX、HTML、LaTeX 等格式\n\n详细说明请参考：[https://opendatalab.github.io/MinerU/reference/output_files/](https://opendatalab.github.io/MinerU/reference/output_files/)\n\n## 技术实现\n\n本 MCP 服务器使用 Python `requests` 库与 MinerU API 交互：\n\n**URL 输入流程：**\n1. **创建任务**: `POST https://mineru.net/api/v4/extract/task`\n2. **查询状态**: `GET https://mineru.net/api/v4/extract/task/{task_id}`\n3. **下载结果**: `GET {zip_url}` 流式下载到本地\n\n**本地文件输入流程：**\n1. **申请上传链接**: `POST https://mineru.net/api/v4/file-urls/batch`\n2. **上传文件**: `PUT {upload_url}` 上传文件内容\n3. **系统自动提交解析任务**\n4. **查询批量结果**: `GET https://mineru.net/api/v4/extract-results/batch/{batch_id}`\n5. **下载结果**: `GET {zip_url}` 流式下载到本地\n\n**大文件处理流程（\u003e200MB PDF）：**\n1. **智能拆分**: 同时考虑大小(180MB)和页数(600页)约束\n2. **逐片上传**: 每个分片独立上传和处理\n3. **分别下载**: 每个分片结果独立下载\n\n## 故障排除\n\n### 问题：Token 无效\n\n请确保：\n1. 从官网正确复制了 Token\n2. Token 前后没有空格\n3. Token 未过期\n\n### 问题：解析失败\n\n可能原因：\n1. 文件 URL 无法访问\n2. 文件格式不支持（请检查是否在支持列表中）\n3. 文件为空（0字节）\n4. 网络问题（国外 URL）\n\n### 问题：大文件拆分失败\n\n可能原因：\n1. 未安装 PyPDF2（运行 `pip install PyPDF2\u003e=3.0.0`）\n2. 非 PDF 格式的大文件无法自动拆分，需手动缩小\n\n## 许可证\n\nMIT License\n\n## 相关链接\n\n- [MinerU 官网](https://mineru.net)\n- [MinerU 文档](https://opendatalab.github.io/MinerU/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favatarganymede%2Fmineru-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favatarganymede%2Fmineru-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favatarganymede%2Fmineru-mcp/lists"}