README.md
Convert PDF, Word, PPT, and images into Markdown using MinerU API
MinerU MCP Server
基于 FastMCP 3.x 的 MCP 服务器，将 MinerU 的文档转 Markdown API 暴露为 MCP 工具。
支持 PDF、Word、PPT 及图片格式（JPG、PNG）的解析。
工具
| 工具 | 说明 |
|---|---|
parse_documents |
将文件转换为 Markdown（支持本地路径和 URL，可批量处理） |
get_ocr_languages |
获取 OCR 支持的语言列表 |
安装
pip install mineru-mcp-server
从源码安装：
git clone https://github.com/Tongzhao9417/mineru_mcp.git
cd mineru_mcp
pip install -e .
核心依赖仅 3 个：fastmcp>=3.0.0、python-dotenv>=1.0.0、httpx>=0.24.0
环境变量
在项目根目录创建 .env 文件（参考 .env.example），或直接设置环境变量：
| 变量 | 说明 | 默认值 |
|---|---|---|
MINERU_API_KEY |
MinerU API 密钥（官网申请） | 必填 |
MINERU_API_BASE |
远程 API 基础 URL | https://mineru.net |
OUTPUT_DIR |
转换结果保存路径 | ./downloads |
USE_LOCAL_API |
是否使用本地 API | false |
LOCAL_MINERU_API_BASE |
本地 API 地址（USE_LOCAL_API=true 时生效） |
http://localhost:8080 |
MCP 客户端配置
Claude Code / Claude Desktop
{
"mcpServers": {
"mineru-mcp": {
"command": "mineru-mcp-server",
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
}
}
从源码运行
{
"mcpServers": {
"mineru-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/mineru_mcp", "run", "mineru-mcp-server"],
"env": {
"MINERU_API_KEY": "your-api-key"
}
}
}
}
直接运行
# stdio 模式（默认，MCP 客户端自动管理）
mineru-mcp-server
# HTTP 模式（独立服务，多客户端可连接）
mineru-mcp-server --transport streamable-http --port 8001
推荐使用
streamable-http传输模式（MCP 规范推荐），SSE 已被标记为 deprecated。
parse_documents 参数
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
file_sources |
string | 文件路径或 URL，多个用逗号分隔 | 必填 |
enable_ocr |
bool | 启用 OCR | false |
language |
string | 文档语言（ch/en 等） |
ch |
page_ranges |
string | 页码范围，如 "2,4-6"（仅远程 API） |
None |
常见问题
API 返回 401：检查 MINERU_API_KEY 是否正确设置。
找不到文件：请使用绝对路径。
调用超时：大文档处理耗时较长，建议分批处理或使用本地 API 模式。
License
MIT
Tools (2)
parse_documentsConvert files to Markdown, supporting local paths and URLs with batch processing capabilities.get_ocr_languagesRetrieve the list of languages supported by the OCR engine.Environment Variables
MINERU_API_KEYrequiredMinerU API key obtained from the official websiteMINERU_API_BASEBase URL for the remote MinerU APIOUTPUT_DIRDirectory path where converted results are savedUSE_LOCAL_APIToggle to use a local MinerU API instanceLOCAL_MINERU_API_BASEURL for the local API instance when USE_LOCAL_API is trueConfiguration
claude_desktop_config.json
{"mcpServers": {"mineru-mcp": {"command": "mineru-mcp-server", "env": {"MINERU_API_KEY": "your-api-key"}}}}Try it
→Convert the PDF file located at /documents/report.pdf into Markdown format.
→Convert this URL https://example.com/presentation.pptx to Markdown and enable OCR for English text.
→Get the list of all languages currently supported by the OCR engine.
→Convert the first 5 pages of /data/manual.pdf to Markdown using the Chinese language setting.