file-analysis-mcp

A personal MCP server that reads unstructured documents (PDF, PPTX, DOCX, SVG, PNG, and other images) in a specified folder and passes the raw text/images as-is so that the calling host (Claude Code, Codex CLI, etc.) can summarize the contents and analyze the folder structure.

This server does not perform summarization itself — it only extracts text and returns images as-is; the actual summarization is done by the LLM (Claude Code/Codex) that calls this tool. No separate API key is required.

Provided Tools

• list_folder_structure(path, max_depth=5) Recursively explores the specified folder and returns the tree structure, file count by extension, and total size as JSON.

• read_document(path, max_chars=20000, max_pages=30) Extracts content based on the file extension and returns it as text/images.

  • .pdf → per-page text

  • .pptx → per-slide text + notes

  • .docx → paragraph/heading/table text

  • .svg → raw XML + rasterized PNG image (when possible)

  • .png / .jpg / .jpeg / .bmp / .gif / .webp → image as-is (after resizing)

Related MCP server: File Context MCP Server

Installation

uv manages both the Python interpreter and dependencies.

cd file-analysis-mcp
uv sync

Local Testing (MCP Inspector)

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

In the Inspector UI that opens in your browser, you can directly call list_folder_structure and read_document. Sample PDF/PPTX/DOCX/SVG/PNG files are prepared in the test_samples/ folder, so you can test right away.

Registering with Claude Code

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

It is already registered at the user scope with the command above and is available in all projects. New MCP servers are loaded at session start, so you must restart Claude Code (or start a new session) for the tools to appear. Check registration status: claude mcp list

Registering with Codex CLI

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

It is already registered globally. Check: codex mcp list

Usage Example (in a new session after registration)

"Analyze the structure of the C:\Users\me\Documents\reports folder and summarize the documents in it"

If you make a request like this, Claude Code/Codex will first understand the structure with list_folder_structure, then call read_document on the needed files to read the contents and summarize them directly.

Notes / Limitations

• Since paths are passed as arguments on each call, there is no access folder restriction (allowlist). It is intended for personal use in a trusted local environment.

• Text is limited by _chars and PDFs by _pages to prevent context overflow. If you need content, you can the values when the call.

• SVG rasterization (svglib) not fully support some complex SVG features (filters some gradients, etc.). Even if it fails, the raw XML text is always returned.