file-analysis-mcp

Liest unstrukturierte Dokumente (PDF, PPTX, DOCX, SVG, PNG und andere Bilder) in einem angegebenen Ordner und übergibt den Originaltext/die Originalbilder unverändert an den aufrufenden Host (Claude Code, Codex CLI usw.), damit dieser Inhaltszusammenfassungen und Ordnerstrukturanalysen durchführen kann. Es handelt sich um einen persönlichen MCP-Server.

Dieser Server führt selbst keine Zusammenfassungen durch – er extrahiert lediglich Text und gibt Bilder unverändert zurück. Die eigentliche Zusammenfassung übernimmt das LLM (Claude Code/Codex), das dieses Tool aufruft. Es ist kein separater API-Schlüssel erforderlich.

Bereitgestellte Tools

• list_folder_structure(path, max_depth=5) Durchsucht den angegebenen Ordner rekursiv und gibt die Baumstruktur, die Dateianzahl nach Erweiterung und die Gesamtgröße als JSON zurück.

• read_document(path, max_chars=20000, max_pages=30) Extrahiert je nach Erweiterung den Inhalt und gibt ihn als Text/Bild zurück.

  • .pdf → Text pro Seite

  • .pptx → Text pro Folie + Notizen

  • .docx → Text aus Absätzen/Überschriften/Tabellen

  • .svg → Original-XML + gerastertes PNG-Bild (falls möglich)

  • .png / .jpg / .jpeg / .bmp / .gif / .webp → Bild unverändert (nach Größenanpassung)

Related MCP server: File Context MCP Server

Installation

uv verwaltet sowohl den Python-Interpreter als auch alle Abhängigkeiten.

cd file-analysis-mcp
uv sync

Lokaler Test (MCP Inspector)

npx @modelcontextprotocol/inspector uv run --directory . python server.py

In der im Browser geöffneten Inspector-UI können Sie list_folder_structure und read_document direkt aufrufen und testen. Im Ordner test_samples/ sind PDF/PPTX/DOCX/SVG/PNG-Beispieldateien vorbereitet, sodass Sie sofort testen können.

Bei Claude Code registrieren

claude mcp add file-analysis -s user -- uv run --directory "C:\Users\20210\Desktop\testmcp\file-analysis-mcp" python server.py

Der Server wurde mit dem obigen Befehl bereits im Benutzerbereich (user scope) registriert und ist in allen Projekten verfügbar. Neue MCP-Server werden beim Start einer Sitzung geladen. Daher müssen Sie Claude Code neu starten (oder eine neue Sitzung beginnen), damit das Tool erscheint. Registrierungsstatus prüfen: claude mcp list

Bei Codex CLI registrieren

codex mcp add file-analysis -- uv run --directory "C:\Users\20210\Desktop\testmcp\file-analysis-mcp" python server.py

Der Server ist bereits global registriert. Prüfen: codex mcp list

Verwendungsbeispiel (in einer neuen Sitzung nach der Registrierung)

Wenn Sie z. B. Folgendes anfragen:

„Analysiere die Struktur des Ordners C:\Users\me\Documents\Berichte und fasse die darin enthaltenen Dokumente zusammen"

erkennt Claude Code/Codex die Struktur über list_folder_structure und ruft anschließend read_document für die benötigten Dateien auf, um den Inhalt zu lesen und selbst zusammenzufassen.

Hinweise / Einschränkungen

• Da Pfade bei jedem Aufruf als Argument übergeben werden, gibt es keine Zugriffsbeschränkung (Allowlist) für Ordner. Die Nutzung ist für den persönlichen Gebrauch in einer vertrauenswürdigen lokalen Umgebung gedacht.

• Die Textlänge wird über max_chars und bei PDFs über max_pages begrenzt, um eine Überlastung des Kontexts zu verhindern. Wenn längere Inhalte benötigt werden, können Sie die Werte beim Aufruf erhöhen.

• Die SVG-Rasterung (svglib) unterstützt möglicherweise nicht alle komplexen SVG-Funktionen (Filter, einige Verläufe usw.) vollständig. Selbst bei einem Fehler wird der Original-XML-Text immer zurückgegeben.