Local Documents MCP Server

📚 本地文档MCP服务器

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

✨ 特性

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

🛠️ 可用工具

• list_documents：按路径、名称和扩展名查找文档
• load_documents：提取文档内容作为标记
• load_scanned_document：使用OCR从扫描的PDF中提取文本

💻 系统要求

• 操作系统：Windows 10/11
• python：3.13或更高
• 程序包管理器: 紫外线 （推荐）

📋 先决条件安装

1.🐍 Python 3.13

从以下网址下载并安装Python 3.13 python.org

2.⚡ UV包装管理器

使用pip安装uv：

pip install uv

3.📖 Windows版Poppler

目的：PDF处理和转换为OCR图像所需。

1. 从以下网址下载最新的Poppler Windows版本：

https://github.com/oschwartz10612/poppler-windows/releases/

1. 将ZIP文件解压缩到：

   D:\Program Files\poppler-24.08.0

1. Poppler二进制文件应位于：

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

备选地点：您可以在任何目录中安装Poppler，只需确保更新 .env 使用正确路径的文件。

4.👁️ Tesseract OCR

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

1. 从以下网址下载Windows版Tesseract：

https://github.com/UB-Mannheim/tesseract/wiki

1. 按照安装程序说明安装Tesseract

1. 确保Tesseract已添加到系统PATH中，或记下安装目录

🚀 工程安装

1.📥 克隆或下载项目

git clone 
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桌面配置

将以下配置添加到您的Claude桌面 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加载配置的设置时，服务器会自动启动。

🔄 可用操作

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

📊 响应格式

服务器返回结构化响应，其中包含：

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

🛠️ 故障排除

⚠️ 常见问题

1. 🔍 未找到Poppler

- 验证Poppler安装路径 - 检查 .env 文件配置 - 确保路径在Windows中使用双反斜杠

1. 👁️ 未找到Tesseract

- 验证Tesseract安装 - 将Tesseract添加到系统PATH - 重新启动命令提示符/PPowerShell

1. 🔐 权限被拒绝错误

- 确保文档目录可访问 - 检查文件权限 - 必要时以管理员身份运行

1. ❌ 导入错误

- 验证是否安装了所有依赖项： uv sync - 检查Python版本： python --version - 确保你使用的是Python 3.13

1. ⏳ 大型文档处理

- 降低令牌限制以获得更好的性能 - 考虑拆分大型文档 - 监控OCR操作期间的内存使用情况

🐛 调试信息

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

📁 文件结构

LocalDocs/
├── server.py              # Main MCP server
├── pyproject.toml         # Project dependencies
├── .env                   # Environment configuration
├── README.md              # This documentation
├── src/
│   └── instructions.md    # Assistant instructions
└── utils/
    ├── __init__.py
    ├── markitdown.py      # Document conversion
    ├── max_tokens.py      # Token management
    ├── ocr.py             # OCR processing
    ├── path_files.py      # File discovery
    └── prompts.py         # Instruction loading

📄 支持的文档格式

• 📊 微软：.docx、.xlsx、.pptx
• 📖 可移植文档格式：常规PDF和扫描PDF（通过OCR）

⚡ 性能注意事项

• 🔍 OCR处理：扫描的文档处理时间要长得多
• 🎯 令牌限制：根据您的文档大小和Claude的上下文窗口进行调整
• 💾 内存使用：大型文档和OCR操作可能会占用大量内存

🤝 贡献

在为该项目做出贡献时：

1. 确保与Windows和Python 3.13的兼容性
2. 使用各种文档格式进行测试
3. 使用扫描文档验证OCR功能
4. 更新任何新功能的文档

📚 相关文件

• MCP文件
• 克劳德桌面MCP指南
• PDF2图像
• Poppler PDF处理
• Tesseract OCR
• MarkItDown

🗺️ 路线图和未来增强功能

🔮 计划的功能

• 🧠 矢量存储和RAG集成：未来的版本将包括矢量文档存储，以：

- 通过避免重复的文本提取来减少令牌消耗 - 启用跨文档集合的语义搜索 - 提供更高效的文档检索和分块 - 支持持久文档索引

• 🔍 增强的OCR验证：目前，扫描书籍的OCR功能尚未完全验证，可能会遇到以下问题：

- 复杂的布局和格式 - 多栏文档 - 扫描质量差 - 非标准字体或语言

💡 当前建议

🚀 对于大型上下文模型

• 🤖 Gemini模型：使用1M以上的令牌上下文窗口，您可以在不截断的情况下处理很长的文档
• 🎯 许可证管理：默认情况下，当前实现最多支持128K个令牌，但可以针对更大的上下文模型进行调整
• 📖 文档处理：在使用以下工具时，考虑使用更高的令牌限制（例如500K-1M）：

- 完整的书籍或长篇报告 - 多个相关文档 - 综合文档分析

⚠️ 需要考虑的限制

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