file-analysis-mcp

지정한 폴더 안의 비정형 문서(PDF, PPTX, DOCX, SVG, PNG 등 이미지)를 읽어, 호출하는 호스트(Claude Code, Codex CLI 등)가 내용 요약과 폴더 구조 분석을 할 수 있도록 원문 텍스트/이미지를 그대로 전달하는 개인용 MCP 서버입니다.

이 서버는 요약을 직접 수행하지 않습니다 — 텍스트를 추출하고 이미지를 그대로 반환할 뿐이며, 실제 요약은 이 도구를 호출한 LLM(Claude Code/Codex)이 수행합니다. 별도 API 키가 필요 없습니다.

제공 도구

• list_folder_structure(path, max_depth=5) 지정 폴더를 재귀 탐색해 트리 구조, 확장자별 파일 개수, 총 용량을 JSON으로 반환.

• read_document(path, max_chars=20000, max_pages=30) 확장자에 따라 내용을 추출해 텍스트/이미지로 반환.

  • .pdf → 페이지별 텍스트

  • .pptx → 슬라이드별 텍스트 + 노트

  • .docx → 문단/제목/표 텍스트

  • .svg → 원문 XML + 래스터화된 PNG 이미지(가능한 경우)

  • .png / .jpg / .jpeg / .bmp / .gif / .webp → 이미지 그대로(리사이즈 후)

Related MCP server: File Context MCP Server

설치

uv가 파이썬 인터프리터와 의존성을 모두 관리합니다.

cd file-analysis-mcp
uv sync

로컬 테스트 (MCP Inspector)

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

브라우저에서 열리는 Inspector UI에서 list_folder_structure, read_document를 직접 호출해볼 수 있습니다. test_samples/ 폴더에 PDF/PPTX/DOCX/SVG/PNG 샘플 파일이 준비되어 있어 바로 테스트 가능합니다.

Claude Code에 등록

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

이미 위 명령으로 사용자 범위(user scope)에 등록되어 모든 프로젝트에서 사용 가능합니다. 새 MCP 서버는 세션 시작 시 로드되므로, Claude Code를 재시작(또는 새 세션 시작)해야 도구가 나타납니다. 등록 상태 확인: claude mcp list

Codex CLI에 등록

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

이미 전역(global)으로 등록되어 있습니다. 확인: codex mcp list

사용 예시 (등록 후 새 세션에서)

"C:\Users\me\Documents\보고서 폴더의 구조를 분석하고, 안에 있는 문서들을 요약해줘"

라고 요청하면 Claude Code/Codex가 list_folder_structure로 구조를 파악한 뒤 필요한 파일들에 read_document를 호출해 내용을 읽고 직접 요약합니다.

참고 / 제한사항

• 경로는 호출할 때마다 인자로 넘기는 방식이라 접근 폴더 제한(allowlist)은 걸려있지 않습니다. 신뢰하는 로컬 환경에서 개인용으로 사용하는 것을 전제로 합니다.

• 텍스트는 max_chars, PDF는 max_pages로 길이를 제한해 컨텍스트 폭주를 방지합니다. 더 긴 내용이 필요하면 호출 시 값을 늘려서 요청하면 됩니다.

• SVG 래스터화(svglib)는 일부 복잡한 SVG 기능(필터, 그라디언트 일부 등)을 완벽히 지원하지 않을 수 있습니다. 실패해도 원문 XML 텍스트는 항상 반환됩니다.