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 文本。