文档阅读器-mcp

Name: 文档阅读器-mcp
Author: ifmelate

作者：ifmelate2 星标更新：2025-10-25

安装使用来源：spider==github.com

项目介绍

document-reader-mcp

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

跨平台兼容：在macOS、Linux和Windows上无缝运行，具有相同的功能。

支持的格式

格式	扩展名	依赖项	状态
PDF	`.pdf`	`pdfminer.six`, `pymupdf`	✅ 包含（文本 + 图像）
Excel	`.xlsx`, `.xlsm`, `.xltx`, `.xltm`	`openpyxl`	✅ 包含
Word	`.docx`	`python-docx`	✅ 包含
CSV	`.csv`	内置	✅ 始终可用
纯文本	`.txt`, `.log`, `.text`	内置	✅ 始终可用
JSON	`.json`	内置	✅ 始终可用
Markdown	`.md`, `.markdown`	内置	✅ 始终可用

功能

✅ 跨平台：在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

# 克隆仓库
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# 创建虚拟环境并安装依赖项
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows（命令提示符）

# 克隆仓库
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# 创建虚拟环境并安装依赖项
python -m venv .venv
.venv\Scripts\activate.bat
pip install -r requirements.txt

Windows（PowerShell）

# 克隆仓库
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# 创建虚拟环境并安装依赖项
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

# 克隆仓库
git clone https://github.com/ifmelate/document-reader-mcp.git
cd document-reader-mcp

# 构建Docker镜像
docker build -t document-reader-mcp:latest .

请参阅下方的Docker配置，了解如何设置MCP客户端。

运行服务器

安装后，启动MCP服务器：

python -m server.main

该服务器通过标准输入输出与兼容MCP的客户端集成。

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

对于Cursor IDE

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

macOS/Linux: ~/.cursor/mcp.json
Windows: %APPDATA%\Cursor\User\globalStorage\mcp.json 或通过设置 → MCP

macOS/Linux 配置

{
  "mcpServers": {
    "document-reader": {
      "command": "python3",
      "args": ["-m", "server.main"],
      "cwd": "/绝对路径/到/document-reader-mcp"
    }
  }
}

Windows 配置

{
  "mcpServers": {
    "document-reader": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "C:\\Users\\您的用户名\\document-reader-mcp"
    }
  }
}

重要提示：对于Windows用户：

在JSON路径中使用双反斜杠 (\\)，或使用正斜杠 (/)，这在Windows上也有效。
将 您的用户名 替换为您实际的Windows用户名。
确保 python 命令指向您的Python 3.10+安装（检查方法：python --version）。

对于Claude Desktop或其他MCP客户端

将类似的配置添加到您客户端的MCP设置文件中，根据需要调整路径。

Docker配置

要使用Docker版本与MCP客户端一起使用：

{
  "mcpServers": {
    "document-reader": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/绝对路径/到/文档:/documents:ro",
        "document-reader-mcp:latest"
      ]
    }
  }
}

重要注意事项：

将 /绝对路径/到/文档 替换为包含要处理文件的目录。
-v 标志将您的文档目录挂载为容器内的 /documents（只读）。
使用 -i 进入交互模式（用于标准输入输出通信）。
使用 --rm 自动移除停止后的容器。
在MCP工具调用中使用的文件路径应采用 /documents/filename.pdf 格式。

多个卷挂载：

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

{
  "mcpServers": {
    "document-reader": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/Users/您/Documents:/documents:ro",
        "-v", "/Users/您/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", "/绝对路径/到/文档:/documents:ro",
        "document-reader-mcp:latest"
      ]
    }
  }
}

Docker的安全考虑：

容器以非root用户（UID 1000）运行。
卷以只读方式挂载（:ro），确保安全。
不暴露网络端口。
容器具有最小的攻击面。

可用工具

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

工具：`extract_text_from_file`

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

参数：

path（字符串，必需）：文档的绝对或相对路径
max_pages（整数，可选）：对于PDF，仅解析前N页（默认：50，设为0禁用）
max_rows（整数，可选）：对于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（整数，可选）：对于PDF，页面上限（默认：50，设为0禁用）
max_rows（整数，可选）：对于CSV/Excel，行上限（默认：500，设为0禁用）
chunk_size（整数，可选）：每段字符数（默认：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

示例用法：

# 将带有图像的Word文档转换为Markdown
result = convert_to_markdown(
    path="/路径/到/document.docx",
    output_dir="/路径/到/输出"
)
# 创建：/路径/到/输出/document.md
#       /路径/到/输出/document_images/image_1.png
#       /路径/到/输出/document_images/image_2.png

重要注意事项：

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

使用示例

在Cursor聊天中：

从~/Downloads/report.pdf中提取文本并总结发现

读取CSV文件data.csv并显示前10行

config.json文件里有什么？

将Word文档~/Documents/proposal.docx转换为Markdown并保存到~/Documents/markdown/

将这个Excel文件转换为Markdown：~/data/sales_report.xlsx

程序化使用：

# 通过MCP客户端 - 提取文本
result = await client.call_tool("extract_text_from_file", {
    "path": "/路径/到/document.pdf",
    "max_pages": 5
})

# 流式处理大型文件
async for chunk in client.stream_tool("extract_text_from_file_stream", {
    "path": "/路径/到/large_file.csv",
    "chunk_size": 8192
}):
    print(chunk)

# 转换为Markdown
result = await client.call_tool("convert_to_markdown", {
    "path": "/路径/到/document.docx",
    "output_dir": "/路径/到/输出",
    "output_filename": "converted_document"
})
print(f"Markdown保存到：{result['markdown_path']}")
print(f"提取的图像数量：{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_PAGES：PDF的默认最大页数（默认：50，设为0禁用）仅限
- 不应用于：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模型的上下文窗口（通常为200K-1M令牌）。这些默认值可以防止上下文溢出，同时允许特定用例的灵活性。当达到限制时，工具会提供明确的警告，并指示如何调整它们。

技术细节

文件大小限制

最大文件大小：100 MB
大于此大小的文件将被拒绝并产生错误

编码检测

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

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

按格式的依赖项

格式	库	类型
PDF（文本）	`pdfminer.six`	包含
PDF（图像）	`pymupdf`	包含
Excel	`openpyxl`	包含
Word	`python-docx`	包含
CSV	`csv`（标准库）	内置
TXT	文件I/O（标准库）	内置
JSON	`json`（标准库）	内置
Markdown	文件I/O（标准库）	内置
转换	`markitdown`	包含

安全考虑

⚠️ 重要：此服务器从文件系统读取本地文件。

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

故障排除

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

检查文件扩展名是否匹配支持的格式之一
支持的格式：.pdf, .xlsx, .xlsm,

文档阅读器-mcp

项目介绍

document-reader-mcp

支持的格式

功能

安装

方案1：从GitHub安装（推荐）

macOS/Linux

Windows（命令提示符）

Windows（PowerShell）

快速设置脚本

方案2：直接通过pip安装

方案3：Docker

运行服务器

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

对于Cursor IDE

macOS/Linux 配置

Windows 配置

对于Claude Desktop或其他MCP客户端

Docker配置

可用工具

工具：extract_text_from_file

工具：extract_text_from_file_stream

工具：convert_to_markdown

使用示例

在Cursor聊天中：

程序化使用：

配置

环境变量

技术细节

文件大小限制

编码检测

按格式的依赖项

安全考虑

故障排除

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

工具：`extract_text_from_file`

工具：`extract_text_from_file_stream`

工具：`convert_to_markdown`