local-docs-mcp

Ein persönlicher MCP-Server, der Dokumente auf dem lokalen PC liest und beim Zusammenfassen und Ordnen hilft. Er extrahiert Text aus PDF, Word, Excel, PowerPoint, HWP, Markdown, CSV usw. und verarbeitet das Speichern von Zusammenfassungen sowie die Dateiorganisation mit einem Genehmigungsverfahren.

• Er nutzt kein Netzwerk. Es sind keine API-Schlüssel erforderlich.

• Das Zusammenfassen übernimmt dieser Server nicht. Er extrahiert den Originaltext präzise; die Zusammenfassung schreibt Claude. (Die vom Server gelieferten machine_keypoints sind eine frequenzbasierte maschinelle Extraktion und keine Zusammenfassung.)

• Außerhalb der erlaubten Ordner kann er nicht lesen. Beim Verschieben oder Speichern von Dateien ist immer eine Genehmigung erforderlich.

Unterstützte Formate

.doc, .xls, .ppt (alte Binärformate) werden nicht gelesen; stattdessen wird empfohlen, sie „im Format mit x zu speichern“.

Related MCP server: Knowledge Assistant MCP

Installation

Python 3.11 oder höher ist erforderlich.

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

Unter macOS und Linux wird .venv/bin/pip verwendet. [formats] installiert pypdf für PDF und olefile für .hwp (binär); ohne sie funktionieren die übrigen Formate weiterhin.

Registrierung in Claude Code

<PROJECT_DIR> ist der absolute Pfad, in den dieses Repository geklont wurde, <HOME> das Benutzer-Home-Verzeichnis.

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

Wenn Sie es nur innerhalb dieses Repositories verwenden möchten, kopieren Sie .mcp.json.example in .mcp.json und ersetzen Sie <PROJECT_DIR> und <HOME> durch die tatsächlichen Pfade. .mcp.json wird nicht im Repository nachverfolgt, da die Pfade je nach Maschine unterschiedlich sind.

Umgebungsvariablen

11 Werkzeuge

Sie werden getrennt als schreibgeschützt (R) und schreibend (W) registriert, sodass der Host unterschiedliche Genehmigungs-UI anzeigen kann.

Empfohlener Ablauf

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

Das Organisieren erfolgt separat.

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

Es gibt vier Organisationskriterien.

Sicherheitsvorkehrungen

1. Pfad-Sperre – Alle Eingabepfade werden nach resolve() daraufhin geprüft, ob sie innerhalb der erlaubten Roots liegen. .., symbolische Links und Laufwerkswechsel werden hier blockiert.

2. Schreib-Sperre – Das Speichern ist nur innerhalb des Ausgabeordners möglich. In die Lese-Roots wird nicht geschrieben.

3. Ausgeschlossene Ordner – .git, node_modules, .venv, AppData usw. werden weder durchsucht noch gelesen.

4. Genehmigungstoken – Es ist der Hash des Vorschauinhalts. Ändert sich auch nur ein Zeichen des Inhalts, wird das Token ungültig und Speichern/Organisieren wird abgelehnt. Das Token gewährleistet jedoch nur technische Integrität und ersetzt nicht die Benutzergenehmigung.

5. Standard ist Kopieren – Das Verschieben von Originalen ist nur mit DOCS_MCP_ALLOW_MOVE=1 möglich.

6. Kein Löschen – Auch das Rückgängigmachen löscht keine Dateien, sondern verschiebt sie in den Ordner _trash.

Verifizierung

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

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

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

• pytest – Extraktion pro Format, Grenzprüfungen, Genehmigungsablauf (Unit)

• smoke.py – Prüft initialize → tools/list → tools/call über echtes stdio

• simulate.py – Erstellt einen virtuellen Dokumentensatz und reproduziert den gesamten Ablauf über eine echte MCP-Verbindung. Es werden 12 virtuelle Dokumente erstellt (Sitzungsprotokolle, Verträge, Angebote, Präsentationen, PDF, CP949-Notizen usw.) und der Ablauf von Durchsuchen → Zusammenfassung speichern → Organisieren → Rückgängigmachen durchlaufen. Dabei wird geprüft, ob blockierte Vorgänge (Lesen außerhalb der Roots, Token-Fälschung, Verschieben von Originalen) tatsächlich blockiert werden. Es läuft in einem temporären Ordner und räumt sich am Ende selbst auf. Um Ergebnisse zu behalten, übergeben Sie einen Ordner als Argument.

Einschränkungen

• Gescannte Bild-PDFs enthalten keinen Text. Es wird kein OCR durchgeführt, nur eine Warnung ausgegeben.

• Excel-Datumszellen können als interne Seriennummern erscheinen.

• .hwp (binär) ist eine bestmögliche Extraktion. Die Reihenfolge von Tabellen und Fußnoten kann vom Original abweichen.

• Text in Bildern wird in keinem Format gelesen.

Lizenz

MIT – LICENSE