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がPythonインタープリタと依存関係をすべて管理します。

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テキストは常に返されます。