local-docs-mcp
local-docs-mcp
一个读取本地 PC 文档、帮助进行摘要和整理的个人 MCP 服务器。 它可以把 PDF、Word、Excel、PowerPoint、韩文、Markdown、CSV 等提取为文本,并在批准流程中处理摘要保存和文件整理。
不使用网络。不需要 API 密钥。
摘要并非由本服务器生成。 只要准确提取出原文,摘要就由 Claude 来写。 (服务器提供的
machine_keypoints是基于频率的机器提取,不是摘要。)无法读取允许的文件夹之外的内容。移动或保存文件时,必须经过批准。
支持的格式
类型 | 扩展名 | 方式 |
文档 |
| ZIP+XML 直接解析(标题·段落·表格) |
韩文 |
| hwpx 默认支持, |
|
| |
演示文稿 |
| 按幻灯片编号顺序 + 演讲者备注 |
表格 |
| 按工作表,解析共享字符串 |
数据 |
| 包含列名·行数 |
网页·邮件 |
| 去除标签,邮件为头部+正文 |
文本·代码 |
| UTF-8/CP949/EUC-KR 自动识别 |
对于 .doc .xls .ppt(旧二进制格式),不会读取,而是提示“请保存为带 x 的格式”。
Related MCP server: file-analysis
安装
需要 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),宿主会显示不同的批准界面。
工具 | 作用 | |
R |
| 查看可读取的文件夹·支持的格式·限制 |
R |
| 扫描文件夹,获取文档列表(类型·大小·修改日期) |
R |
| 结构·标题·关键词·代表句。用于在阅读全文前判断 |
R |
| 提取正文。提供分区标签和续读游标 |
R |
| 在多个文档正文中搜索 + 依据片段 |
R |
| 在字数预算内从多个文档中均衡摘录 |
R |
| 预览要保存的内容·路径 + 发放批准令牌 |
W |
| 将已批准的摘要保存到输出文件夹 |
R |
| 仅生成整理计划(不改变文件)+ 发放批准令牌 |
W |
| 执行已批准的计划(默认复制) |
W |
| 仅依据日志记录进行回滚 |
推荐流程
list_roots
→ scan_documents 어떤 문서가 있는지
→ outline_document 긴 문서는 뼈대부터
→ read_document 원문을 근거로 확보 (필요하면 이어 읽기)
→ (Claude가 요약 작성)
→ preview_save_summary 저장 내용 확인
→ [사용자 승인]
→ save_summary整理会单独进行。
preview_organize 계획만 생성 — 파일은 하나도 건드리지 않음
→ [사용자가 계획 확인·승인]
→ apply_organize (기본 copy)
→ 문제가 있으면 undo_last_organize整理标准共有以下四种。
标准 | 结果文件夹 |
|
|
| 类似 |
|
|
| 在规则中指定的名称。例如: |
安全机制
路径封锁 — 所有输入路径都先经过
resolve()解析,再确认是否位于允许的根目录内。..、符号链接、跨驱动器访问都会在这里被阻止。写入封锁 — 只能保存到输出文件夹内。不会写入读取根目录。
排除文件夹 —
.gitnode_modules.venvAppData等既不会扫描也不会读取。批准令牌 — 是预览内容的哈希。只要内容有一个字符不同,令牌就会失效,保存和整理都会被拒绝。但令牌只保证技术完整性,不能代替用户批准。
默认是复制 — 只有设置了
DOCS_MCP_ALLOW_MOVE=1才能移动原文件。不删除 — 回滚也不会删除文件,而是移动到
_trash文件夹。
验证
.venv/Scripts/python.exe -m pytest -q.venv/Scripts/python.exe scripts/smoke.py.venv/Scripts/python.exe scripts/simulate.pypytest— 按格式的提取·边界检查·批准流程(单元)smoke.py— 通过实际 stdio 验证initialize → tools/list → tools/callsimulate.py— 创建虚拟文档集,在真实 MCP 连接下复现整个流程。会生成会议记录、合同、报价、演示文稿、PDF、CP949 备忘录等 12 个虚拟文档,然后依次进行扫描 → 保存摘要 → 整理 → 回滚,并确认应当被阻止的事情(读取根目录之外、伪造令牌、移动原文件)确实被阻止。它在临时文件夹中运行,结束后会自动清理。如果想保留结果,请传入一个文件夹作为参数。
限制
扫描图片型 PDF 没有文本。不做 OCR,只留下警告。
Excel 的日期单元格可能显示为内部序列号。
.hwp(二进制)为尽力提取。表格、脚注的顺序可能与原文不同。图片中的文字在任何格式下都不会被读取。
许可证
MIT — LICENSE
Available Tools
11 toolsapply_organizeADestructive
승인된 정리 계획을 실제로 수행합니다. 기본은 복사이며, 이동은 서버 설정과 사용자 승인이 모두 있어야 합니다.
Inputs: target_dir (required), approval_token (required), mode, kinds, +5 more. Returns: mode, stage, status, journal, +5 more
build_summary_bundleARead-only
여러 문서를 글자 예산 안에서 고르게 발췌해 한 번에 돌려줍니다. 여러 문서를 묶어 요약할 때 씁니다.
Inputs: paths (required), char_budget. Returns: stage, status, included, documents, +6 more
list_rootsARead-only
이 서버가 읽을 수 있는 폴더, 저장 위치, 지원 형식과 한도를 확인합니다. 다른 도구를 부르기 전에 먼저 호출하세요.
Inputs: no named parameters. Returns: roots, stage, limits, status, +4 more
outline_documentARead-only
문서를 열어 구조(구역·제목·분량)와 키워드를 돌려줍니다. 전문을 읽기 전에 어디를 읽을지 고를 때 씁니다.
Inputs: path (required), keypoint_limit. Returns: kind, path, stage, status, +9 more
preview_organizeARead-only
문서를 어떤 폴더로 나눌지 계획만 만들어 보여줍니다. 파일을 전혀 건드리지 않습니다.
Inputs: target_dir (required), kinds, limit, folder, +3 more. Returns: plan, stage, total, status, +9 more
preview_save_summaryARead-only
요약문을 저장하기 전에 최종 파일 경로와 내용을 미리 보여주고 승인 토큰을 발급합니다. 파일을 쓰지 않습니다.
Inputs: title (required), sources (required), summary_markdown (required), note, +1 more. Returns: stage, status, reminder, target_path, +5 more
read_documentARead-only
문서 본문을 텍스트로 읽습니다. 구역 라벨([p.3], [슬라이드 2] 등)이 함께 붙어 요약에 근거를 달 수 있습니다.
Inputs: path (required), max_chars, start_char, only_labels. Returns: kind, path, text, stage, +8 more
save_summaryA
사용자가 승인한 요약을 출력 폴더에 저장합니다. preview_save_summary의 토큰이 필요합니다.
Inputs: title (required), sources (required), approval_token (required), summary_markdown (required), +2 more. Returns: path, bytes, stage, status, +2 more
scan_documentsARead-only
허용 폴더를 훑어 문서 목록을 최근 수정순으로 돌려줍니다. 파일 내용은 읽지 않습니다.
Inputs: kinds, limit, folder, name_pattern, +1 more. Returns: count, files, stage, stats, +3 more
search_documentsBRead-only
여러 문서의 본문을 실제로 열어 검색어를 찾고, 주변 문장을 근거 스니펫으로 돌려줍니다.
Inputs: query (required), kinds, folder, max_files. Returns: hits, count, query, stage, +4 more
undo_last_organizeADestructive
가장 최근(또는 지정한) 정리 실행을 되돌립니다. 복사본은 지우지 않고 _trash 폴더로 옮깁니다.
Inputs: journal_path. Returns: mode, stage, status, journal, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose: listing roots, scanning, outlining, reading, searching, bundling summaries, preview/save summaries, preview/apply organize, and undo. No two tools appear to overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_roots, scan_documents, preview_organize). Even compound verbs like preview_save_summary maintain the pattern.
11 tools is well-scoped for a local docs management server, covering read, search, summarize, save, and organize workflows without bloat. Each tool earns its place in the workflow.
The tool surface covers the full lifecycle for reading and managing documents: listing, scanning, outlining, reading, searching, bundling, saving summaries with preview, organizing with preview and apply, and undo for corrections. No obvious dead ends or missing operations for the stated purpose.
Maintenance
Related MCP Connectors
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Convert PDF pages into editable Word-ready text from your AI chat, all offline.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Convert PDF, Word, Excel and scanned documents to Markdown, tables and RAG chunks. OCR.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with local documents (PDF, Markdown, TXT) through tools for discovery, reading, extraction, summarization, comparison, keyword extraction, search, and analysis, ensuring privacy and offline capability.-
- FlicenseAqualityDmaintenanceEnables local analysis of unstructured documents (PDF, DOCX, PPTX, SVG, PNG) by extracting text and structure with citation anchors, and verifies summaries against source material before a human approves saving a report.9-
- FlicenseAqualityDmaintenanceEnables read-only scanning and text extraction from PDF, DOCX, PPTX, SVG, and PNG files in a local folder, providing the raw text to AI models for summarization or analysis without an external LLM API.5-
- FlicenseAqualityBmaintenanceEnables AI assistants to read local documents by converting PDFs, Office files, images, and audio to Markdown on-device, without uploading them.470 npm-