local-docs-mcp

一个读取本地 PC 文档、帮助进行摘要和整理的个人 MCP 服务器。 它可以把 PDF、Word、Excel、PowerPoint、韩文、Markdown、CSV 等提取为文本，并在批准流程中处理摘要保存和文件整理。

• 不使用网络。不需要 API 密钥。

• 摘要并非由本服务器生成。 只要准确提取出原文，摘要就由 Claude 来写。 （服务器提供的 machine_keypoints 是基于频率的机器提取，不是摘要。）

• 无法读取允许的文件夹之外的内容。移动或保存文件时，必须经过批准。

支持的格式

对于 .doc .xls .ppt（旧二进制格式），不会读取，而是提示“请保存为带 x 的格式”。

Related MCP server: Knowledge Assistant MCP

安装

需要 Python 3.11 或更高版本。

python -m venv .venv && .venv/Scripts/pip install -e ".[formats,dev]"

macOS · Linux 使用 .venv/bin/pip。[formats] 会同时安装用于 PDF 的 pypdf 和用于 .hwp（二进制）的 olefile；即使没有它们，其余格式也可以正常运行。

在 Claude Code 中注册

<PROJECT_DIR> 是克隆此仓库的绝对路径，<HOME> 是用户主文件夹。

claude mcp add local-docs --scope user --env DOCS_MCP_ROOTS="<HOME>/Desktop;<HOME>/Documents" --env DOCS_MCP_OUTPUT="<HOME>/Desktop/docs-mcp-out" -- <PROJECT_DIR>/.venv/Scripts/python.exe -m docs_mcp.server

如果只想在这个仓库内使用，请将 .mcp.json.example 复制为 .mcp.json，然后把 <PROJECT_DIR> 和 <HOME> 替换为实际路径。.mcp.json 会因机器不同而路径不同，因此不会纳入仓库跟踪。

环境变量

11 个工具

由于注册时区分了只读（R）和写入（W），宿主会显示不同的批准界面。

推荐流程

list_roots
  → scan_documents          어떤 문서가 있는지
  → outline_document        긴 문서는 뼈대부터
  → read_document           원문을 근거로 확보 (필요하면 이어 읽기)
  → (Claude가 요약 작성)
  → preview_save_summary    저장 내용 확인
  → [사용자 승인]
  → save_summary

整理会单独进行。

preview_organize   계획만 생성 — 파일은 하나도 건드리지 않음
  → [사용자가 계획 확인·승인]
  → apply_organize (기본 copy)
  → 문제가 있으면 undo_last_organize

整理标准共有以下四种。

安全机制

1. 路径封锁 — 所有输入路径都先经过 resolve() 解析，再确认是否位于允许的根目录内。..、符号链接、跨驱动器访问都会在这里被阻止。

2. 写入封锁 — 只能保存到输出文件夹内。不会写入读取根目录。

3. 排除文件夹 — .git node_modules .venv AppData 等既不会扫描也不会读取。

4. 批准令牌 — 是预览内容的哈希。只要内容有一个字符不同，令牌就会失效，保存和整理都会被拒绝。但令牌只保证技术完整性，不能代替用户批准。

5. 默认是复制 — 只有设置了 DOCS_MCP_ALLOW_MOVE=1 才能移动原文件。

6. 不删除 — 回滚也不会删除文件，而是移动到 _trash 文件夹。

验证

.venv/Scripts/python.exe -m pytest -q

.venv/Scripts/python.exe scripts/smoke.py

.venv/Scripts/python.exe scripts/simulate.py

• pytest — 按格式的提取·边界检查·批准流程（单元）

• smoke.py — 通过实际 stdio 验证 initialize → tools/list → tools/call

• simulate.py — 创建虚拟文档集，在真实 MCP 连接下复现整个流程。会生成会议记录、合同、报价、演示文稿、PDF、CP949 备忘录等 12 个虚拟文档，然后依次进行扫描 → 保存摘要 → 整理 → 回滚，并确认应当被阻止的事情（读取根目录之外、伪造令牌、移动原文件）确实被阻止。它在临时文件夹中运行，结束后会自动清理。如果想保留结果，请传入一个文件夹作为参数。

限制

• 扫描图片型 PDF 没有文本。不做 OCR，只留下警告。

• Excel 的日期单元格可能显示为内部序列号。

• .hwp（二进制）为尽力提取。表格、脚注的顺序可能与原文不同。

• 图片中的文字在任何格式下都不会被读取。

许可证

MIT — LICENSE