file-analysis-mcp

Servidor MCP personal que lee documentos no estructurados (PDF, PPTX, DOCX, SVG, PNG y otras imágenes) de una carpeta especificada y entrega el texto/imagen originales tal cual, para que el host que realiza la llamada (Claude Code, Codex CLI, etc.) pueda resumir el contenido y analizar la estructura de la carpeta.

Este servidor no realiza el resumen directamente — solo extrae texto y devuelve las imágenes tal cual; el resumen real lo lleva a cabo el LLM (Claude Code/Codex) que llama a esta herramienta. No se necesita ninguna clave API adicional.

Herramientas proporcionadas

• list_folder_structure(path, max_depth=5) Explora la carpeta especificada de forma recursiva y devuelve en JSON la estructura de árbol, el número de archivos por extensión y el tamaño total.

• read_document(path, max_chars=20000, max_pages=30) Extrae el contenido según la extensión y lo devuelve como texto/imagen.

  • .pdf → texto por página

  • .pptx → texto por diapositiva + notas

  • .docx → texto de párrafos/títulos/tablas

  • .svg → XML original + imagen PNG rasterizada (si es posible)

  • .png / .jpg / .jpeg / .bmp / .gif / .webp → imagen tal cual (tras redimensionar)

Related MCP server: File Context MCP Server

Instalación

uv gestiona tanto el intérprete de Python como las dependencias.

cd file-analysis-mcp
uv sync

Prueba local (MCP Inspector)

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

Desde la UI del Inspector, que se abre en el navegador, puede llamar directamente a list_folder_structure y read_document. En la carpeta test_samples/ hay archivos de muestra PDF/PPTX/DOCX/SVG/PNG preparados para probar de inmediato.

Registro en Claude Code

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

Ya está registrado en el ámbito de usuario (user scope) con el comando anterior y se puede usar en todos los proyectos. Como los nuevos servidores MCP se cargan al inicio de la sesión, debe reiniciar Claude Code (o iniciar una nueva sesión) para que la herramienta aparezca. Para comprobar el estado del registro: claude mcp list

Registro en Codex CLI

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

Ya está registrado a nivel global. Verificación: codex mcp list

Ejemplo de uso (en una sesión nueva tras el registro)

"Analiza la estructura de C:\Users\me\Documents\보고서 폴더 y resume los documentos que contiene."

Si se hace esta petición, Claude Code/Codex identificará la estructura con list_folder_structure y, a continuación, llamará a read_document en los archivos necesarios para leer el contenido y resumirlo directamente.

Notas / Limitaciones

• Las rutas se pasan como argumento en cada llamada, por lo que no hay una restricción de carpetas de acceso (allowlist). Se asume un uso personal en un entorno local de confianza.

• La longitud del texto se limita con max_chars y la de los PDF con max_pages para evitar la saturación del contexto. Si necesita contenido más extenso, aumente estos valores al hacer la llamada.

• La rasterización de SVG (svglib) puede no ser totalmente compatible con algunas funciones SVG complejas (filtros, ciertos degradados, etc.). Aunque falle, siempre se devuelve el texto XML original.