本地文档MCP工具

作者：Baronco1 星标更新：2025-07-07

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

项目介绍

📚 本地文档 MCP 服务器

一个用于与 Windows 系统上的本地文档进行交互的模型上下文协议（MCP）服务器。该服务器提供了工具来列出、加载和处理文档，并支持对扫描的 PDF 进行 OCR 处理。

✨ 特性

📁 文档发现：列出指定目录中的所有文档
⚡ 文档处理：将各种文档格式转换为 Markdown
🔍 OCR 支持：使用 Tesseract OCR 从扫描的 PDF 中提取文本
🎯 令牌管理：基于令牌限制自动截断内容
📄 多格式支持：处理 Word 文档、PDF、PowerPoint、Excel 等

🛠️ 可用工具

list_documents：通过路径、名称和扩展名查找文档
load_documents：将文档内容提取为 Markdown
load_scanned_document：使用 OCR 从扫描的 PDF 中提取文本

💻 系统需求

操作系统：Windows 10/11
Python：3.13 或更高版本
包管理器：uv（推荐）

📋 先决条件安装

1. 🐍 Python 3.13

从 python.org 下载并安装 Python 3.13

2. ⚡ UV 包管理器

使用 pip 安装 uv：

pip install uv

3. 📖 Poppler for Windows

目的：用于 PDF 处理和转换为图像以供 OCR 使用。

从以下地址下载最新版本的 Poppler Windows 发行版： https://github.com/oschwartz10612/poppler-windows/releases/
将 ZIP 文件解压到：
```
D:\Program Files\poppler-24.08.0
```

Poppler 的二进制文件应位于：

D:\Program Files\poppler-24.08.0\Library\bin

替代位置：您可以在任何目录中安装 Poppler，只需确保更新 .env 文件中的正确路径。

4. 👁️ Tesseract OCR

目的：用于从扫描文档和图像中提取文本。

从以下地址下载适用于 Windows 的 Tesseract： https://github.com/UB-Mannheim/tesseract/wiki
按照安装程序说明安装 Tesseract
确保 Tesseract 已添加到系统 PATH 中，或记录安装目录

🚀 项目安装

1. 📥 克隆或下载项目

git clone <your-repo-url>
cd LocalDocs

2. 📦 安装 Python 依赖项

uv sync

这将根据 pyproject.toml 安装所有必需的依赖项：

markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.2 - 文档转换
mcp[cli]>=1.10.1 - MCP 服务器框架
opencv-python>=4.11.0.86 - 图像处理
pdf2image>=1.17.0 - PDF 转换为图像
pytesseract>=0.3.13 - Tesseract OCR 包装器
python-dotenv>=1.1.1 - 环境变量管理
tiktoken>=0.9.0 - 令牌计数

3. ⚙️ 配置环境变量

在项目根目录创建或更新 .env 文件：

POPPLER_PATH="D:\\Program Files\\poppler-24.08.0\\Library\\bin"

注意：更新路径以匹配您的 Poppler 安装位置。

🔧 对 MCP 客户端的配置

🤖 Claude Desktop 配置

向您的 Claude Desktop config.json 文件添加以下配置：

第一个参数：指向您的文档目录的路径
- 示例："C:\Users\YourUsername\Documents\MyDocuments"
- 在 JSON 中使用双反斜杠表示 Windows 路径
第二个参数：每个文档的最大令牌数
- 示例："30000"
- 根据您的需求和 Claude 的令牌限制进行调整

📝 示例配置

对于不同的文档位置：

{
  "mcpServers": {
    "local-documents": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\YourUsername\\Documents\\LocalDocs",
        "run",
        "server.py",
        "C:\\Users\\YourUsername\\Documents\\MyDocuments",
        "30000"
      ]
    }
  }
}

🎯 使用方法

🚀 启动服务器

当 Claude Desktop 加载带有配置设置时，服务器会自动启动。

🔄 可用操作

📋 列出文档：发现配置目录中的所有文档
📄 加载标准文档：处理 Word 文档、PDF、PowerPoint、Excel 文件
🔍 加载扫描文档：使用 OCR 从扫描的 PDF 中提取文本

📊 响应格式

服务器返回结构化的响应，包括：

文档路径和元数据
令牌使用信息
处理时间（针对 OCR 操作）
提取的内容以 Markdown 格式呈现

🛠️ 故障排除

⚠️ 常见问题

🔍 找不到 Poppler
- 验证 Poppler 安装路径
- 检查 .env 文件配置
- 确保 Windows 路径使用双反斜杠
👁️ 找不到 Tesseract
- 验证 Tesseract 安装
- 将 Tesseract 添加到系统 PATH
- 重启命令提示符/PowerShell
🔐 权限被拒绝错误
- 确保文档目录可访问
- 检查文件权限
- 如有必要，请以管理员身份运行
❌ 导入错误
- 验证所有依赖项已安装：uv sync
- 检查 Python 版本：python --version
- 确保使用的是 Python 3.13
⏳ 大文档处理
- 减少令牌限制以提高性能
- 考虑拆分大文档
- 监控 OCR 操作期间的内存使用情况

🐛 调试信息

要获取更详细的错误信息，请检查 Claude Desktop 日志或在 PowerShell 窗口中手动运行服务器。

📁 文件结构

LocalDocs/
├── server.py              # 主 MCP 服务器
├── pyproject.toml         # 项目依赖项
├── .env                   # 环境配置
├── README.md              # 本文档
├── src/
│   └── instructions.md    # 助手指令
└── utils/
    ├── __init__.py
    ├── markitdown.py      # 文档转换
    ├── max_tokens.py      # 令牌管理
    ├── ocr.py             # OCR 处理
    ├── path_files.py      # 文件发现
    └── prompts.py         # 指令加载

📄 支持的文档格式

📊 Microsoft Office：.docx, .xlsx, .pptx
📖 PDF：常规 PDF 和扫描的 PDF（通过 OCR）

⚡ 性能考虑

🔍 OCR 处理：扫描文档需要显著更长时间来处理
🎯 令牌限制：根据您的文档大小和 Claude 的上下文窗口进行调整
💾 内存使用：大型文档和 OCR 操作可能非常占用内存

🤝 贡献

贡献于此项目时：

确保兼容 Windows 和 Python 3.13
测试各种文档格式
验证扫描文档的 OCR 功能
更新文档以反映新功能

📚 相关文档

MCP 文档
Claude Desktop MCP 指南
PDF2Image
[Poppler PDF 处理](https://github.com/oschwartz1 12/poppler-windows/releases/)
Tesseract OCR
MarkItDown

🗺️ 路线图和未来增强

🔮 计划功能

🧠 向量存储和 RAG 集成：未来版本将包括矢量文档存储，以：
- 通过避免重复提取文本减少令牌消耗
- 实现跨文档集合的语义搜索
- 提供更高效的文档检索和分块
- 支持持久文档索引
🔍 增强 OCR 验证：目前，扫描书籍的 OCR 功能尚未完全验证，可能会遇到以下问题：
- 复杂布局和格式
- 多列文档
- 质量差的扫描
- 非标准字体或语言

💡 当前建议

🚀 对于大型上下文模型

🤖 Gemini 模型：具有 1M+ 令牌上下文窗口，可以处理非常长的文档而不截断
🎯 令牌管理：当前实现默认支持高达 128K 令牌，但可以根据更大的上下文模型进行调整
📖 文档处理：考虑使用更高的令牌限制（例如，500K-1M），当处理：
- 完整书籍或长报告
- 多个相关文档
- 综合文档分析

⚠️ 需要考虑的限制

🔍 OCR 可靠性：扫描文档处理是实验性的，可能需要手动验证
⏳ 处理时间：大型文档和 OCR 操作可能耗时较长
💾 内存使用：高分辨率扫描文档可能需要大量的系统资源