Skip to main content
Glama
file-analyzer-mcp

file-analyzer-mcp

Proof

Point it at a folder and it hands back a real tree, not a guess:

$ analyze_folder_structure({ "folder_path": "tests/fixtures" })
{
  "status": "OK",
  "file_count": 6,
  "supported_file_count": 6,
  "extension_stats": [
    { "extension": ".pdf",  "count": 2, "bytes": 723995 },
    { "extension": ".docx", "count": 1, "bytes": 35505 },
    { "extension": ".pptx", "count": 1, "bytes": 33067 },
    { "extension": ".svg",  "count": 1, "bytes": 319 },
    { "extension": ".png",  "count": 1, "bytes": 74 }
  ],
  "tree_text": "fixtures/\n├── sample.docx (34.7KB)\n├── sample.pdf (431B)\n├── sample.png (74B)\n├── sample.pptx (32.3KB)\n├── sample.svg (319B)\n└── sample_scanned.pdf (706.6KB)"
}

Then read one of them — headings, paragraphs, and tables come back structured, not flattened:

$ read_docx({ "file_path": "tests/fixtures/sample.docx" })
{
  "status": "OK",
  "headings": ["테스트 문서"],
  "text": "테스트 문서\n본문 첫 문단입니다.",
  "tables": [{ "index": 0, "rows": [["A", "B"], ["1", "2"]] }]
}

Both calls are reproducible — clone this repo, run uv sync --extra dev, and call them against tests/fixtures/ yourself.

Related MCP server: file-analyzer

What it is

A personal MCP server that reads whatever's in a folder — PDF, Word, PowerPoint, SVG, PNG — and hands the structure and raw content back to whichever agent called it (Claude Code, Claude Desktop, Codex). It doesn't summarize anything itself.

That's the whole design: the server extracts, the host interprets. No LLM API key lives in this server. A PNG comes back as base64 image content, not a caption — your host's own vision reads it. A scanned PDF only gets OCR'd when you ask for it.

Tools

Tool

Role

analyze_folder_structure

Recursive tree + per-extension stats for a folder

list_supported_files

Just the pdf/docx/pptx/svg/png paths, filtered

read_pdf

Per-page text. ocr=True runs Tesseract on pages with no text layer

read_docx

Paragraphs, headings, tables (.doc not supported)

read_pptx

Per-slide title, body, speaker notes (.ppt not supported)

read_svg

Size, tag counts, <text> content — no rasterizing

read_image

PNG as metadata + image content, for the host to look at directly

Large documents paginate: page_start/page_end for PDF, slide_start/slide_end for PPTX. Default caps are 30 pages / 60 slides — past that, the response's next_actions tells you the next range to ask for.

Install

uv sync --extra dev

Register with Claude Code:

claude mcp add -s user file-analyzer -- "<uv.exe path>" --directory "<this folder>" run python src/file_analyzer_mcp/server.py

On Windows, if uv was installed via pip it won't be on Claude's PATH — use uv.exe's full path (pip show uv to find it). Claude Desktop and Codex examples are in config/: claude_code.example.md, claude_desktop_config.example.json, codex-config.example.toml.

Security

Sensitive paths are refused deterministically — this doesn't depend on the model deciding not to read them. See paths.py.

Pattern

What it protects

.ssh, .aws, .gnupg, .azure, .kube, .docker

Credential and cloud-config directories

Browser profile roots (e.g. User Data)

Saved logins and cookies

.env*, *.pem, *.key, *.pfx, *.p12

Secret files, matched by name pattern

id_rsa, id_ed25519, known_hosts, .netrc, credentials, credentials.json, login data, cookies, web data

Specific credential filenames

Every call is also audited — tool name, arguments, and outcome (success or blocked) get appended to logs/audit.jsonl. See audit.py. A 50MB file size cap applies on top of all of this.

Conventions for anyone extending this server are in AGENTS.md.

Errors

Every failure raises ToolFailure with a code, a plain-language reason, and how to recover — the message is written for the calling model to read and act on, not just for a human.

Code

Raised when

PATH_NOT_FOUND

The folder or file path doesn't exist

NOT_A_DIRECTORY / NOT_A_FILE

A tool got the wrong kind of path

UNSUPPORTED_EXTENSION

The file isn't pdf/docx/pptx/svg/png

WRONG_TOOL_FOR_EXTENSION

e.g. read_pdf called on a .docx

FILE_TOO_LARGE

File exceeds the 50MB cap

SENSITIVE_PATH_BLOCKED

Path matches the security table above

OCR_ENGINE_NOT_FOUND

ocr=True but Tesseract isn't installed/configured

SVG_PARSE_ERROR

The .svg file isn't valid XML

Scanned-PDF OCR

read_pdf(ocr=True) needs Tesseract:

winget install UB-Mannheim.TesseractOCR
uv run python scripts/setup_ocr.py   # copies eng/osd, downloads kor.traineddata

ocr_lang defaults to "kor+eng". Wrong Tesseract path? Set TESSERACT_CMD.

Testing

uv run pytest -q                        # parser / path / audit unit tests
uv run python scripts/smoke_stdio.py    # real stdio round-trip against the server

Both should pass before a change counts as done — pytest checks modules in isolation, the smoke test is the only thing that exercises the actual MCP protocol and catches schema-level breakage.

Limits

Limit

Why / what to do

.doc / .ppt not supported

Legacy binary formats — save as .docx/.pptx first

Scanned PDFs return empty text by default

Pass ocr=True (off by default — it's slower)

SVGs aren't rasterized

Parsed as XML for structure, not rendered as an image

Available Tools

7 tools
analyze_folder_structureA
Read-onlyIdempotent

지정한 폴더를 재귀적으로 훑어 트리, 확장자별 통계를 돌려준다.

파일 분석의 출발점입니다. 여기서 폴더 규모를 먼저 파악한 뒤, list_supported_files로 실제로 읽을 수 있는 파일만 추리세요.

Args: folder_path: 분석할 폴더 경로. max_depth: 트리 최대 깊이 (기본 5). max_entries: 트리에 나열할 최대 항목 수 (기본 2000).

Returns: FolderStructureResponse: tree_text에 들여쓰기된 트리, extension_stats에 확장자별 개수/용량, truncated에 상한 초과 여부.

Inputs: folder_path (required), max_depth, max_entries. Returns: root, status, dir_count, tree_text, +6 more

list_supported_filesA
Read-onlyIdempotent

폴더 안에서 pdf/docx/pptx/svg/png 파일만 골라 경로 목록으로 돌려준다.

각 항목의 absolute_path를 read_pdf/read_docx/read_pptx/read_svg/read_image에 그대로 넘기면 됩니다.

Args: folder_path: 분석할 폴더 경로. max_depth: 탐색 최대 깊이 (기본 5). max_entries: 탐색할 최대 항목 수 (기본 2000).

Returns: SupportedFilesResponse: files[]에 relative_path/absolute_path/extension/bytes.

Inputs: folder_path (required), max_depth, max_entries. Returns: root, count, files, status, +2 more

read_docxA
Read-onlyIdempotent

Word(.docx) 문서의 본문 문단, 제목, 표를 추출한다.

옛 형식(.doc)은 지원하지 않습니다 — Word에서 '다른 이름으로 저장 > .docx'로 변환한 뒤 다시 시도하세요.

Args: file_path: docx 파일 경로. max_chars: 본문 최대 글자 수 (기본 60000).

Returns: ReadDocxResponse: text(본문), headings(제목 스타일 문단), tables(행 단위 셀 텍스트).

Raises: ToolFailure: PATH_NOT_FOUND / NOT_A_FILE / FILE_TOO_LARGE / UNSUPPORTED_EXTENSION.

Inputs: file_path (required), max_chars. Returns: text, status, tables, headings, +4 more

read_imageA
Read-onlyIdempotent

PNG 이미지를 읽어 메타데이터와 이미지 콘텐츠를 함께 돌려준다.

이 도구는 이미지를 요약하지 않는다. 반환된 이미지를 직접 보고 내용을 설명/요약하는 것은 호출자(당신)의 역할입니다.

Args: file_path: png 파일 경로.

Returns: list: [메타데이터(JSON), 이미지 콘텐츠] 두 항목. 메타데이터에는 width/height/mime_type이 담깁니다.

Raises: ToolFailure: PATH_NOT_FOUND / NOT_A_FILE / FILE_TOO_LARGE / UNSUPPORTED_EXTENSION.

Inputs: file_path (required).

read_pdfA
Read-onlyIdempotent

PDF에서 페이지별 텍스트를 추출한다.

긴 PDF는 컨텍스트를 아끼기 위해 page_start/page_end로 범위를 지정해 나눠 읽으세요. page_end를 생략하면 기본 상한(30페이지)까지만 읽고, 그 이상은 truncated 여부 대신 total_pages와 end_page 차이로 알 수 있습니다.

Args: file_path: PDF 파일 경로. page_start: 시작 페이지 (기본 1). page_end: 끝 페이지. 생략 시 최대 30페이지. ocr: 텍스트 레이어가 없는 페이지를 OCR로 보강할지 여부 (기본 False, 느립니다). ocr_lang: OCR 언어 코드 (기본 'kor+eng').

Returns: ReadPdfResponse: pages[]에 페이지별 text와 text_source ('extracted'/'ocr'/'empty'). likely_scanned가 True면 원래 텍스트 레이어가 없는 스캔본 — ocr=True로 다시 호출하면 내용을 읽을 수 있습니다.

Raises: ToolFailure: PATH_NOT_FOUND / NOT_A_FILE / FILE_TOO_LARGE / UNSUPPORTED_EXTENSION / OCR_ENGINE_NOT_FOUND.

Inputs: file_path (required), ocr, ocr_lang, page_end, +1 more. Returns: pages, status, end_page, metadata, +5 more

read_pptxA
Read-onlyIdempotent

PowerPoint(.pptx)에서 슬라이드별 제목, 본문, 스피커 노트를 추출한다.

옛 형식(.ppt)은 지원하지 않습니다. 슬라이드가 많으면 slide_start/slide_end로 나눠 읽으세요.

Args: file_path: pptx 파일 경로. slide_start: 시작 슬라이드 (기본 1). slide_end: 끝 슬라이드. 생략 시 최대 60장.

Returns: ReadPptxResponse: slides[]에 slide_number/title/text/notes.

Raises: ToolFailure: PATH_NOT_FOUND / NOT_A_FILE / FILE_TOO_LARGE / UNSUPPORTED_EXTENSION.

Inputs: file_path (required), slide_end, slide_start. Returns: slides, status, end_slide, file_path, +3 more

read_svgA
Read-onlyIdempotent

SVG의 크기, 태그별 구조 통계, 텍스트 요소를 추출한다.

SVG는 XML이라 별도 렌더링 없이 구조 파악이 가능합니다. 단, 이 도구는 벡터를 래스터화(이미지로 렌더링)하지 않으므로, 텍스트가 거의 없고 순수 도형으로만 이루어진 다이어그램은 element_counts로 복잡도만 짐작할 수 있습니다.

Args: file_path: svg 파일 경로.

Returns: ReadSvgResponse: element_counts(태그별 개수), text_content(text 요소 모음), title/description(/ 값).

Raises: ToolFailure: PATH_NOT_FOUND / NOT_A_FILE / FILE_TOO_LARGE / UNSUPPORTED_EXTENSION.

Inputs: file_path (required). Returns: title, width, height, status, +6 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each read_* tool targets a distinct file format (pptx, svg, image, pdf, docx) with clear boundaries; list_supported_files and analyze_folder_structure have separate discovery roles. No overlap or ambiguity exists.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern: read_<format> for content extraction, plus list_supported_files and analyze_folder_structure. Conventions are uniform and predictable.

    Tool Count5/5

    Seven tools is well-scoped for a file analyzer server: five format readers plus two discovery/analysis helpers. Each tool has a clear purpose and none feel redundant or missing.

    Completeness5/5

    The server covers all explicitly supported formats (pdf, docx, pptx, svg, png) with read operations, and provides folder-level discovery through list_supported_files and analyze_folder_structure. The surface is complete for its stated analysis purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to inspect and convert PDF, PowerPoint, Excel, and many other file formats into clean, structured Markdown, with chunking support for long documents.
      Apache 2.0
    • 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
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables LLM hosts like Claude Code or Codex CLI to inspect folder structures and read unstructured documents (PDF, PPTX, DOCX, SVG, and images) by returning raw text and images for the host to summarize or analyze.
      2
      -
    • F
      license
      A
      quality
      C
      maintenance
      Enables read-only scanning and text extraction from PDF, DOCX, PPTX, SVG, and PNG files in a local folder, providing the raw text to AI models for summarization or analysis without an external LLM API.
      5
      -