Document Reader

文档阅读器-MCP（或“多用途文档阅读器”根据上下文可灵活翻译）

  ](https://github.com/ifmelate/document-reader-mcp/releases) 

通用MCP服务器，用于从各种文档格式中提取文本。支持流式处理、页面/行限制、编码检测以及简单的速率限制。

跨平台兼容在 macOS、Linux 和 Windows 上均可无缝运行，功能一致。

支持的格式

特点/功能

✅ 跨平台适用于 macOS、Linux 和 Windows 系统\ ✅（对号，表示正确、同意或确认） 支持多种格式PDF、Excel、CSV、TXT、JSON、Markdown、DOCX、PowerPoint、HTML\ ✅ Markdown转换将文档转换为Markdown格式，并自动提取图片\ ✅ PDF图像提取自动从PDF中提取并嵌入到适当页面位置的图片\ ✅ 流式传输API高效内存处理大文件\ ✅ 表示“正确”或“已确认”。 智能编码检测处理UTF-8、Latin-1、CP1252、ISO-8859-1编码\ ✅ 情境感知限制自动截断以防止AI上下文溢出\ ✅ 速率限制全局速率限制（可配置）\ ✅ Docker 支持在隔离的容器中以非root用户身份运行\ ✅ 模块化设计易于扩展以支持新格式\ ✅ 最小的依赖大多数格式仅使用Python标准库

安装

选项1：从GitHub安装（推荐）

macOS/Linux（注：macOS是苹果公司的操作系统，Linux是一个开源的计算机操作系统）

# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows（命令提示符）

# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# Create virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt

Windows（PowerShell）

# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# Create virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Windows PowerShell 用户注意事项如果你遇到执行策略错误，请运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

快速设置脚本

为了方便起见，您可以使用提供的设置脚本：

macOS/Linux：

chmod +x dev-setup.sh
./dev-setup.sh

Windows（命令提示符）：

dev-setup.bat

Windows（PowerShell）：

.\dev-setup.ps1

这些脚本将自动创建虚拟环境、安装依赖项并设置开发环境。

选项2：使用pip直接安装

pip install git+https://github.com/ifmelate/document-reader-mcp.git

选项3：Docker

# Clone the repository
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# Build the Docker image
docker build -t document-reader-mcp:latest .

看 以下是MCP客户端的设置说明。

运行服务器

安装完成后，启动MCP服务器：

python -m server.main

该服务器通过标准I/O（stdio）运行，以便与兼容MCP的客户端进行集成。

在Cursor（或其他MCP客户端）中的配置

对于Cursor IDE

将此配置添加到您的 Cursor MCP 设置中：

• macOS/Linux（注：这两个词分别是苹果公司和Linux操作系统的名称，通常不需要翻译，直接使用即可）: ~/.cursor/mcp.json
• Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json 或者通过设置 → MCP（管理控制面板）

macOS/Linux 配置

{
  "mcpServers": {
    "document-reader": {
      "command": "python3",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/document-reader-mcp"
    }
  }
}

Windows 配置

{
  "mcpServers": {
    "document-reader": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "C:\\Users\\YourUsername\\document-reader-mcp"
    }
  }
}

对Windows用户而言很重要：

• 使用双反斜杠（\\在JSON路径中使用反斜杠（），或者使用正斜杠（/）/) 该软件也适用于Windows系统
• 替换 YourUsername 使用您实际的Windows用户名
• 确保 python 命令指向你的 Python 3.10+ 安装目录（检查方法为 python --version)

对于Claude Desktop或其他MCP客户端

在客户端的MCP设置文件中添加类似的配置，并相应调整路径。

Docker 配置

要使用带有MCP客户端的Docker版本：

{
  "mcpServers": {
    "document-reader": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/absolute/path/to/documents:/documents:ro",
        "document-reader-mcp:latest"
      ]
    }
  }
}

重要提示：

• 替换 /absolute/path/to/documents 包含你想要处理的文件的目录
• 这个（或：该） -v 将您的文档目录标记为 /documents 在容器中（只读）
• 使用 -i 用于交互模式（stdio通信所必需）
• 使用 --rm 在容器停止后自动将其移除
• 在MCP工具调用中，文件路径应使用 /documents/filename.pdf 格式

多个卷挂载点：

如果您需要从多个目录访问文件：

{
  "mcpServers": {
    "document-reader": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/Users/you/Documents:/documents:ro",
        "-v", "/Users/you/Downloads:/downloads:ro",
        "document-reader-mcp:latest"
      ]
    }
  }
}

自定义速率限制：

{
  "mcpServers": {
    "document-reader": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "DOC_READER_RATE_LIMIT_PER_MINUTE=120",
        "-v", "/absolute/path/to/documents:/documents:ro",
        "document-reader-mcp:latest"
      ]
    }
  }
}

Docker的安全考量：

• 容器以非root用户（UID 1000）身份运行
• 卷以只读方式挂载（:ro）为了安全起见
• 没有网络端口暴露
• 容器具有最小的攻击面

可用工具

配置完成后，您可以使用以下工具：

工具： extract_text_from_file

从文档文件中提取完整文本。

参数：

• path (字符串，必填)：文档的绝对路径或相对路径
• max_pages (int, 可选)：对于PDF文件，仅解析前N页（默认：50，设置为0以禁用）
• max_rows (int, 可选)：对于CSV/Excel文件，仅解析N行数据（默认：500，设为0以禁用）

返回： 提取的文本作为字符串（默认情况下自动截断为100,000个字符）

支持的格式： .pdf， .xlsx， .xlsm， .csv， .txt， .json， .md， .docx

注： 对于大文件，请使用 extract_text_from_file_stream 而是为了避免内存问题。

默认限制： 为防止AI上下文溢出，该工具采用了合理的默认设置：

• PDF文件：前50页
• Excel/CSV：前500行
• 所有格式：输出限制为100,000个字符

工具： extract_text_from_file_stream

从文档中流式传输文本块（适用于大文件，内存效率高）。

参数：

• path (字符串，必需)：文档的绝对路径或相对路径
• max_pages (int, 可选)：对于PDF文件，页面上限（默认：50，设置为0以禁用）
• max_rows (int, 可选)：对于CSV/Excel文件，行限制（默认：500，设置为0以禁用）
• chunk_size (int, 可选)：每块字符数（默认：4096，最小：512）

产量： 文本块作为字符串

支持的格式： 所有格式均来自 extract_text_from_file

工具： convert_to_markdown

将各种文档格式转换为Markdown格式，并在适用时提取和保存图像。

⚠️ 重要这个工具将 整个文档 并将其保存到文件中。它 忽视 这个（或“它”） DOC_READER_DEFAULT_MAX_ROWS， DOC_READER_DEFAULT_MAX_PAGES，和 DOC_READER_MAX_OUTPUT_CHARS 环境变量。仅返回给AI的预览内容受到限制以保护上下文——保存的文件包含完整文档。

参数：

• path （字符串，必填）：要转换文件的绝对路径或相对路径
• output_dir （字符串，可选）：将Markdown文件和图片保存的目录。如果未指定，则保存在与源文件相同的目录中
• output_filename （字符串，可选）：输出Markdown文件的名称（不含扩展名）。如果未指定，则使用带有.md扩展名的源文件名

返回值： 包含以下内容的字典：

• markdown_path保存的Markdown文件的路径（包含完整内容，未截断）
• images_dir包含提取图像（如有）的目录路径
• image_count提取的图像数量
• markdown_preview前500个字符预览（为保护AI上下文已截断）
• file_size_chars保存的Markdown文件的总字符数
• status“成功”或错误状态
• message可读的状态信息

支持的格式：

• PDF（.pdf) - 具备自动图像提取和页面位置定位功能
• Excel（.xlsx， .xlsm， .xltx， .xltm) - 转换为Markdown表格
• Word（.docx) - 带有图像提取功能
• CSV（逗号分隔值）.csv) - 转换为Markdown表格
• PowerPoint（.pptx) - 文字和图片
• HTML（.html， .htm)
• 纯文本 (.txt， .log）
• 图像（.jpg， .jpeg， .png) - 如有光学字符识别（OCR）功能则使用

示例用法：

# Convert a Word document with images
result = convert_to_markdown(
    path="/path/to/document.docx",
    output_dir="/path/to/output"
)
# Creates: /path/to/output/document.md
#          /path/to/output/document_images/image_1.png
#          /path/to/output/document_images/image_2.png

重要提示：

• 整个文件已保存无论大小，完整的Markdown文件都会被保存到磁盘，不会被截断
• 预览已截断仅返回给AI的预览内容限制为500个字符，以保护上下文信息
• 图片自动从支持的格式中提取并保存在 {filename}_images/ 子目录，使用相对路径在Markdown中引用它们
• PDF图像在Markdown文档中，图片会智能地放置在其对应的页面位置，以便在预览中查看

使用示例

在Cursor聊天中：

Extract text from ~/Downloads/report.pdf and summarize the findings

Read the CSV file data.csv and show me the first 10 rows

What's in the JSON file config.json?

Convert the Word document ~/Documents/proposal.docx to Markdown and save it in ~/Documents/markdown/

Convert this Excel file to Markdown: ~/data/sales_report.xlsx

程序化使用：

# Via MCP client - Extract text
result = await client.call_tool("extract_text_from_file", {
    "path": "/path/to/document.pdf",
    "max_pages": 5
})

# Streaming large files
async for chunk in client.stream_tool("extract_text_from_file_stream", {
    "path": "/path/to/large_file.csv",
    "chunk_size": 8192
}):
    print(chunk)

# Convert to Markdown
result = await client.call_tool("convert_to_markdown", {
    "path": "/path/to/document.docx",
    "output_dir": "/path/to/output",
    "output_filename": "converted_document"
})
print(f"Markdown saved to: {result['markdown_path']}")
print(f"Images extracted: {result['image_count']}")

配置

环境变量

使用这些环境变量配置服务器行为：

• DOC_READER_RATE_LIMIT_PER_MINUTE每分钟最大工具调用次数（默认：60）

- 适用于所有工具

• DOC_READER_MAX_OUTPUT_CHARS最大输出文本字符数（默认：100000）

- 适用于： extract_text_from_file 并且 extract_text_from_file_stream 仅；只有 - 不适用于: convert_to_markdown （保存完整文件，仅预览有限）

• DOC_READER_DEFAULT_MAX_ROWS电子表格/CSV文件的默认最大行数（默认：500，设为0以禁用）

- 适用于： extract_text_from_file 和 extract_text_from_file_stream 仅 - 不适用于: convert_to_markdown （转换整个文档）

• DOC_READER_DEFAULT_MAX_PAGESPDF文件的默认最大页数（默认值：50，设为0以禁用）

- 适用于： extract_text_from_file 和 extract_text_from_file_stream 仅 - 不适用于: convert_to_markdown （转换整个文档）

示例：

export DOC_READER_RATE_LIMIT_PER_MINUTE=120
export DOC_READER_MAX_OUTPUT_CHARS=200000
export DOC_READER_DEFAULT_MAX_ROWS=1000
export DOC_READER_DEFAULT_MAX_PAGES=100
python -m server.main

为什么要设定这些限制？ 大型文档很容易超出AI模型的上下文窗口（通常为20万至100万个标记）。这些默认设置既能防止上下文溢出，又为特定用例提供了灵活性。当达到限制时，工具会提供明确的警告，并附上如何调整这些限制的说明。

技术细节

文件大小限制

• 最大文件大小： 100兆字节
• 大于此大小的文件将被拒绝并报错

编码检测

基于文本的格式（CSV、TXT、JSON、Markdown）会自动尝试多种编码：

• UTF-8
• Latin-1（ISO-8859-1）
• Windows-1252（CP1252）

按格式划分的依赖项

安全考虑事项

⚠️ 重要的这个服务器从文件系统中读取本地文件。

• 切勿将此服务器暴露于不可信网络中
• 仅在受信任的MCP客户端环境中使用（例如，Cursor IDE）
• 速率限制是按进程而非按用户进行的
• 没有内置的身份验证功能
• 文件路径已扩展为 os.path.expanduser() （支持 ~）

故障排除

“不支持的文件类型”错误

• 检查文件扩展名是否与支持的格式之一匹配
• 支持： .pdf， .xlsx， .xlsm， .xltx， .xltm， .docx， .csv， .txt， .log， .json， .md， .markdown

“解码失败”错误

• 该文件可能使用了不支持的文本编码
• 首先尝试将文件转换为UTF-8编码
• 这通常会影响CSV、TXT、JSON和Markdown文件

速率限制已超出

• 增加 DOC_READER_RATE_LIMIT_PER_MINUTE 环境变量
• 或者等待60秒，直到速率限制窗口重置

缺失依赖项错误

• 如果你看到“X 未安装”的错误，请重新安装依赖项： pip install -r requirements.txt
• 对于PDF图像提取问题，请确保已安装PyMuPDF： pip install pymupdf

Windows特有的问题

PowerShell 执行策略错误

如果你看到 cannot be loaded because running scripts is disabled：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

路径长度限制（Windows）

Windows 默认情况下路径长度限制为260个字符。对于长路径：

1. 在Windows 10/11中启用长路径支持： Microsoft Docs（微软文档）
2. 或者将仓库移动到一个更短的路径（例如。， C:\mcp\document-reader)

在Windows上未找到Python

• 确保已安装 Python 3.10+ 并将其添加到 PATH 中
• 与以下内容核对： python --version
• 如果 python 不起作用，试试 py 或者 python3

Windows系统上的虚拟环境激活问题

• 命令提示符：使用 .venv\Scripts\activate.bat
• PowerShell：使用 .venv\Scripts\Activate.ps1
• Git Bash：使用 source .venv/Scripts/activate

与Docker相关的问题

Docker 未运行

• 确保已安装并运行Docker Desktop
• 在Windows上，Docker Desktop需要WSL 2

Docker 卷的权限错误

• 在Windows上，请确保在Docker Desktop设置中已共享该驱动器
• 右键点击 Docker Desktop 图标 → 设置 → 资源 → 文件共享

做出贡献

我们欢迎投稿！请参阅 CONTRIBUTING.md 翻译为中文是：“贡献指南/贡献文档”。这个文件通常用于说明如何向开源项目或软件项目贡献代码、文档或其他资源 关于……的指南：

• 设置您的开发环境
• 代码风格和提交规范
• 添加对新文件格式的支持
• 提交拉取请求

许可证

这个项目遵循MIT许可证授权——详见 许可证 文件中有详细信息。

支持

• 问题：
• 讨论：

版本

当前版本： 1.0.0