local-docs-mcp

A personal MCP server that reads documents on your local PC to help with summarization and organization. It extracts text from PDF, Word, Excel, PowerPoint, Hangul (HWP), Markdown, CSV, and more, and handles saving summaries and organizing files with an approval process.

• It does not use the network. No API key is required.

• This server does not summarize. It extracts the original text accurately, and Claude writes the summary. (The machine_keypoints the server provides are frequency-based mechanical extraction, not a summary.)

• It cannot read outside the allowed folders. Moving or saving files always requires approval.

Supported formats

.doc .xls .ppt (legacy binary formats) are not read; the server tells you to "save them in an x-suffixed format."

Related MCP server: file-analysis

Installation

Python 3.11 or later is required.

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

On macOS and Linux, use .venv/bin/pip. [formats] installs pypdf for PDF and olefile for .hwp (binary) together; without them, the remaining formats still work.

Registering with Claude Code

<PROJECT_DIR> is the absolute path where you cloned this repository, and <HOME> is the user home folder.

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

To use it only within this repository, copy .mcp.json.example to .mcp.json and replace <PROJECT_DIR> and <HOME> with the actual paths. .mcp.json paths differ per machine, so it is not tracked in the repository.

Environment variables

11 tools

Read-only (R) and write (W) tools are registered separately so the host can show different approval UIs.

Recommended flow

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

Organization is done separately.

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

There are four organization criteria.

Safety mechanisms

1. Path blocking — Every input path is resolve()d and then checked to be inside the allowed roots. .., symbolic links, and drive traversal are all blocked here.

2. Write blocking — Saving is only possible inside the output folder. Nothing is written to the read roots.

3. Excluded folders — .git, node_modules, .venv, AppData, etc. are neither scanned nor read.

4. Approval token — A hash of the preview content. If even one character of the content changes, the token breaks and saving/organizing is rejected. However, the token only guarantees technical integrity and does not replace user approval.

5. Copy by default — Moving originals is only possible with DOCS_MCP_ALLOW_MOVE=1.

6. No deletion — Undo also does not delete files; it moves them to a _trash folder.

Verification

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

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

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

• pytest — format-specific extraction, boundary checks, approval flow (unit tests)

• smoke.py — verifies initialize → tools/list → tools/call over real stdio

• simulate.py — creates a virtual document set and reproduces the entire flow over a real MCP connection. It creates 12 virtual documents (meeting minutes, contracts, quotes, presentation materials, PDFs, CP949 memos, etc.), then runs through scanning → summary saving → organization → undo, and verifies that things that should be blocked (reading outside roots, token forgery, moving originals) are actually blocked. It runs in a temporary folder and cleans up after itself. Pass a folder as an argument to keep the results.

Limitations

• Scanned image PDFs have no text. No OCR is performed; only a warning is left.

• Excel date cells may appear as internal serial numbers.

• .hwp (binary) is best-effort extraction. Table and footnote order may differ from the original.

• Text inside images is not read in any format.

License

MIT — LICENSE