Skip to main content
Glama
file-analysis-mcp

file-analysis-mcp

by Seonja-Lee

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.

Available Tools

2 tools
list_folder_structureA

지정한 폴더를 재귀적으로 탐색해 트리 구조, 확장자별 파일 개수, 총 용량을 JSON 문자열로 반환한다.

Inputs: path (required), max_depth. Returns: result

read_documentA

지정한 문서 파일(PDF, PPTX, DOCX, SVG, 이미지)의 내용을 읽어 텍스트/이미지로 반환한다. 반환된 텍스트/이미지를 바탕으로 호출자가 직접 요약을 수행해야 한다.

Inputs: path (required), max_chars, max_pages.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct responsibilities: one summarizes folder structure and statistics, while the other extracts content from document files. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern: list_folder_structure and read_document. The naming is predictable and easy to understand.

    Tool Count3/5

    With only two tools, the server feels minimal and borderline thin for a file-analysis purpose. Each tool is useful, but the overall surface is small and may leave users wanting more capability.

    Completeness3/5

    The pair covers folder structure analysis and document content extraction, but common file types like plain text and CSV are not supported, and there are no file search or metadata retrieval operations. These are notable gaps for a file-analysis server.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Large Language Models to safely browse and interact with local file systems through secure directory listing, file reading, and content search capabilities. Built with comprehensive security controls and high-performance handling of large directories and files.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, search, and analyze local file systems with tools for reading file contents, listing directories, searching by patterns, and analyzing folder structures for context-aware queries.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to generate annotated file trees, retrieve file statistics, list git-changed files, and read file contents from local directories or GitHub repositories.
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Enables read-only analysis of local unstructured documents by scanning a folder, extracting text and structural metadata, and passing content with truncation and error-awareness to an LLM for summarization.
      9
      1
      -