read4all
Optional integration with an OpenAI-compatible VLM endpoint to generate natural-language descriptions for extracted images, which are written into Markdown image alt text for text-only models.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
read4all — 多格式附件提取 MCP Server
把 PDF / Office / 图片 / 网页文档转为 Markdown + 图片的 MCP 工具。MinerU 云端优先(高精度公式/表格/版面)+ 本地库降级(秒级,离线可用),深度提取能力(表格择优/图表几何)融入降级链,唯一转换入口。
flowchart LR
A["附件<br/>PDF/DOCX/PPTX/XLSX/图片/HTML/..."] --> R[read4all MCP Server]
R -->|MinerU 优先| M[MinerU 云端<br/>公式/表格/版面]
R -->|降级| L["本地库(融入深度能力)<br/>pymupdf/pypdf/pdfplumber/MarkItDown"]
R --> O["<附件目录>/<stem>/<stem>.md + images/"]
M -->|内容哈希缓存| R特性
全格式:PDF / DOCX / PPTX / XLSX / 图片 / HTML / EPUB / CSV / JSON / XML / TXT
MinerU 优先 + 本地降级:有 key 走云端高精度(公式/表格/版面),无 key 自动降级本地库(秒级,功能仍可用)
转换与精读分开:
convert_to_markdown负责解析,read_markdown负责按段直读完整解析稿产物同级目录:
<附件目录>/<stem>/<stem>.md + images/,图片按imgN.<ext>命名(MinerU 路径细分 img/table/chart/extraN)内容哈希缓存:同文件重复转换秒级命中,文件改动自动失效
图片理解:
describe_images=True为提取图生成 alt 文本,供纯文本模型"看图"uvx 一键运行:Python 版 npx,
uvx read4all无需预装
Related MCP server: MinerU MCP Server
在 Claude Code 中使用
1. 装 uv
uvx 是 Python 版的 npx,自动从 PyPI 拉取并运行 read4all,无需预装。先装 uv:
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"2. 配置 .mcp.json
在你的项目根(或 ~/.claude.json 全局)创建/编辑 .mcp.json,把 MinerU key 直接写在 env 字段:
{
"mcpServers": {
"read4all": {
"command": "uvx",
"args": ["read4all"],
"env": {
"MINERU_API_KEY": "你的_mineru_token"
}
}
}
}MinerU key 获取:从 https://mineru.net/apiManage 注册 → 复制 token(形如 sk-...),填入上面的 MINERU_API_KEY。
无 key 也能用:不配
env或 key 无效时,read4all 自动降级到本地库(秒级),功能仍可用,只是 PDF 的高精度公式/表格/版面还原能力会弱些。配置后启用 MinerU 云端优先(高精度,最长等待 10 分钟,同文件有内容哈希缓存)。
3. 重启 Claude Code
重启 MCP 客户端后,先调用 convert_to_markdown 解析论文,再把返回的 md_path 交给 read_markdown 分段直读。后续段落使用上一次返回的 next_start_char,避免每轮重新解析或只读到预览。
命令行直接用(不走 MCP)
uvx read4all # 启动 stdio server(供 MCP 客户端)
MINERU_API_KEY=你的token uvx read4all # 带 MinerU key 启动从源码运行(开发者)
git clone https://github.com/int2t05/read4all
cd read4all
pip install -e ".[test]" # 可编辑安装
python -m read4all # 启动 server
pytest test/ -v # 跑本地和 MCP 协议测试源码形态的 .mcp.json(本地构建,未发布时):
{
"mcpServers": {
"read4all": {
"command": "uvx", "args": ["--from", ".", "read4all"],
"env": { "MINERU_API_KEY": "你的_mineru_token" }
}
}
}工具
转换、精读与能力查询共 3 个工具。深度提取能力不单独暴露,而是融入 convert 降级链:
工具 | 说明 | 引擎 |
| 支持格式/引擎/MinerU 状态 | — |
| 全格式 → Markdown + 图片(产物同级目录) | MinerU 优先 + 按格式降级 |
| 按字符偏移分段读取解析稿,直到全文读完 | 本地 Markdown |
convert 的降级链:MinerU 优先(高精度公式/表格/版面),失败按格式降级到本地库——PDF 降级时融入深度能力(表格择优→md table、图表几何标注、嵌入图片存盘),产物更丰富;Office/网页走 MarkItDown;图片直接复制。详见 docs/TECH.md。
describe_images=True 时为提取图跑 MinerU 图片理解,文本写入 alt(供纯文本模型)。
产物契约
输入 <dir>/<stem>.<ext> → 产物落到附件同级目录:
<dir>/
├── <stem>.<ext> ← 原附件
└── <stem>/ ← 同级产物目录
├── <stem>.md ← Markdown(图片以  引用)
└── images/ ← 提取图片,imgN.<ext> 命名(MinerU 路径细分 img/table/chart/extraN)convert_to_markdown 返回 {md_path, images_dir, image_count, table_count, engine_used, fallback_reason, page_count, char_count, preview}(preview = Markdown 前 2000 字符预览,用于确认解析结果)。精读通过 read_markdown(md_path, start_char, max_chars) 读取正文;每段返回 next_start_char,传入下一次调用即可继续,默认每段 12000 字符、上限 50000 字符。
MinerU 默认使用官方推荐的精准解析 API vlm,开启公式和表格识别。默认最长轮询 10 分钟;refresh_mineru=True 可跳过 read4all 本地哈希缓存并重新请求云端。无 key、无效 key、限频、超时或超出 200MB/200 页限制时按格式降级,结果含真实 engine_used 和 fallback_reason。能力查询只表示 key 已配置,不代表服务端验证通过。
图片理解(供纯文本模型)
让非多模态模型也能"看图"——为图片生成文本描述,挂为 alt。通过 convert_to_markdown(describe_images=True) 触发:转换时为每张提取图跑 MinerU 理解,文本写入 alt(供纯文本模型)。
路径 | 引擎 | 产出 | 适用 |
首选 | MinerU | 图片→转 PDF→结构化 OCR 文本 | 文档型图片(截图/扫描/含文字图表) |
扩展点 | VLM | 视觉大模型自然语言描述 | 通用图片(预留 |
降级 | — | 空描述 + | — |
VLM 语义描述扩展(可选,启用通用图片语义,同样配在 .mcp.json 的 env):
"env": {
"MINERU_API_KEY": "你的_mineru_token",
"READ4ALL_VLM_BASE_URL": "https://api.openai.com/v1",
"READ4ALL_VLM_API_KEY": "你的_vlm_key",
"READ4ALL_VLM_MODEL": "gpt-4o-mini"
}未配置 VLM 时 description=None,MinerU 文本(文档型图片)仍可用;配置后通用图片(照片/图表)语义描述启用。
MinerU 内容哈希缓存
MinerU 单次通常需数十秒至数分钟,最长等待 10 分钟。同文件重复转换命中缓存即秒级返回(内容寻址,文件改动自动失效):
缓存键 =
sha1(文件内容)[:16]+ 参数哈希缓存目录:
~/.cache/read4all/mineru/<key>/(存markdown.md+content_list.json+images/)
测试
pip install -e ".[test]"
python -m pytest test/ -v测试夹具在 test/conftest.py 运行时生成(pymupdf 造 PDF/PNG,stdlib zipfile 造 DOCX/XLSX)。本地降级、Markdown 分段读取和缓存行为均可离线验证;云端成功路径需有效 key+网络。
能力边界
仅读,不做 PDF 生成/合并/拆分/表单
本地库不还原矢量路径公式、不做本地 OCR(均需 MinerU)
深度提取(表格择优/图表几何)融入 PDF 降级链,不单独暴露工具;Office/网页无此能力
文档
文档 | 内容 |
技术文档:核心理念、模块结构、路由决策、产物契约、降级机制 | |
三库 + MinerU 实测对照、路由依据、图表数据重建 | |
图片理解竞品调研(OCR vs VLM,三级分层方案) | |
版本变更记录 | |
贡献指南 |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Convert PDFs, Office files, spreadsheets and images to clean Markdown, sized for agent context.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Converts PDF, scans, DOCX, XLSX and PPTX to Markdown with tables and page-aware RAG chunks.
Parse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConverts documents, webpages, and media files into markdown for AI assistants using Microsoft's MarkItDown and Crawl4AI. It enables tools to read PDFs, Office files, and JavaScript-rendered websites with support for OCR and image extraction.3MIT
- AlicenseAqualityDmaintenanceExposes the MinerU document-to-markdown API as MCP tools for converting PDF, Word, PPT, and images into Markdown. It supports both local and remote file processing with integrated OCR capabilities for multiple languages.210MIT
- AlicenseBqualityDmaintenanceConverts documents (PDF, Word, PPT, images, HTML) to Markdown via MinerU API. Supports URL and local file inputs with OCR, formula/table recognition, and automatic large file handling.55MIT
- AlicenseAqualityDmaintenanceConverts files (PDF, DOCX, PPTX, XLSX, images via OCR) and URLs to Markdown, enabling AI clients to read them via a single MCP tool.1GPL 3.0