dataframe-analyst-mcp

Servidor MCP (Model Context Protocol) y CLI para análisis exploratorio de datos (CSV/XLS/XLSX/Google Sheets/Google Drive) y exporte de reportes (md/json/html) a disco local o Google Drive.

Implementado con FastMCP (autogenera los inputSchema a partir de type hints / Pydantic).

Características (no triviales)

Carga de datos desde:
- Local (path a CSV/XLS/XLSX).
- Google Drive (fileId).
- Google Sheets (spreadsheetId + range/sheet opcional).
Herramientas MCP expuestas:
- load_data – carga dataset y deja una vista previa en sesión.
- infer_schema – tipos por columna y metainformación básica.
- missing_report – %/conteo de faltantes por columna.
- profile – estadísticas descriptivas con percentiles configurables.
- correlation – matriz de correlación (pearson/spearman/kendall).
- detect_outliers – detección por IQR o Z-score.
- groupby – agregaciones por clave(s) con métricas parametrizables.
- export_report – exporta reporte md/json/html a local o Drive (carpeta).
CLI fallback incluida (útil para depuración/uso directo).

Requisitos

Python 3.10+ (recomendado 3.11).
pip, setuptools, wheel actualizados.

Instalación

python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate python -m pip install -U pip setuptools wheel # Instala el paquete en modo editable (usa pyproject.toml) python -m pip install -e . # Dependencias base (si no se instalaron automáticamente) python -m pip install mcp pandas openpyxl "xlrd==1.2.0" # (Opcional) extras para Google Drive/Sheets python -m pip install "gspread>=6" "google-auth>=2.28" "google-auth-oauthlib>=1.2" "pydrive2>=1.19"

Nota: xlrd==1.2.0 se requiere solo para .xls antiguos. Para .xlsx se usa openpyxl.

Credenciales Google (opcional)

Service Account (SA) – acceso de lectura a Drive/Sheets

Crea una Service Account en Google Cloud y habilita Drive API y Sheets API.
Descarga la clave JSON a secrets/sa.json (no subir a git).
Exporta:
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/secrets/sa.json"
Comparte el Sheet y/o la carpeta de Drive con el correo de la SA.

OAuth Desktop (para subir a Mi unidad o cuando SA no tiene permisos)

Configura OAuth consent screen (External) y agrega tu correo como Test user.
Crea un OAuth Client ID tipo Desktop y guarda secrets/client_secret.json.
(Opcional, para ruta explícita de token)
export GOOGLE_OAUTH_CLIENT_SECRETS="secrets/client_secret.json" export GOOGLE_OAUTH_TOKEN="secrets/token.json"

Uso como CLI

Ejecuta el modo consola:

python -m dataframe_analyst_mcp.server --cli

Comandos de ejemplo:

# Cargar desde local load_data {"source":{"type":"local","path":"examples/ventas_2023.csv"},"options":{"header":0}} # Cargar desde Google Sheets (usa tu spreadsheetId) load_data {"source":{"type":"gsheet","spreadsheetId":"<SPREADSHEET_ID>"},"options":{"header":0}} # Cargar desde Google Drive (usa tu fileId de un CSV/XLSX/Sheet) load_data {"source":{"type":"gdrive_file","fileId":"<FILE_ID>"},"options":{"header":0}} infer_schema {} missing_report {} profile {"columns":["precio","cantidad"],"percentiles":[0.05,0.5,0.95]} correlation {"method":"pearson"} detect_outliers {"column":"precio","method":"iqr","factor":1.5} groupby {"by":["categoria"],"metrics":{"precio":["mean","max"],"cantidad":["sum"]}} # Exportar reporte a local export_report {"dest":{"type":"local","path":"out/reporte.md"}, "fmt":"md", "sections":["schema","missing","profile","correlation"]} # Exportar a Google Drive (carpeta) export_report {"dest":{"type":"gdrive_folder","folderId":"<FOLDER_ID>"},"fmt":"md","sections":["schema","missing","profile","correlation"]}

Uso como MCP Server (STDIO)

Arranque directo:

python -m dataframe_analyst_mcp.server --mcp

Integración con clientes MCP (config ejemplo)

mcpServers.json:

{ "mcpServers": { "dataframe-analyst": { "command": "python", "args": ["-m", "dataframe_analyst_mcp.server", "--mcp"], "env": { "GOOGLE_APPLICATION_CREDENTIALS": "/ruta/abs/secrets/sa.json", "GOOGLE_OAUTH_CLIENT_SECRETS": "/ruta/abs/secrets/client_secret.json", "GOOGLE_OAUTH_TOKEN": "/ruta/abs/secrets/token.json" } } } }

Smoke test (cliente Python mínimo)

python - <<'PY' import asyncio, json from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client CSV = "/Users/diederichsolis/Desktop/codigos/dataframe-analyst-mcp/examples/ventas_2023.csv" # ajusta ruta si cambiaste el proyecto async def main(): params = StdioServerParameters(command="python", args=["-m","dataframe_analyst_mcp.server","--mcp"]) async with stdio_client(params) as (r,w): async with ClientSession(r,w) as s: await s.initialize() # 1) Cargar datos await s.call_tool("load_data", {"source": {"type":"local","path": CSV}}) # 2) Esquema r = await s.call_tool("infer_schema", {}) print("infer_schema →", r.content[0].text[:240], "...\n") # 3) Perfil r = await s.call_tool("profile", {"percentiles":[0.05, 0.5, 0.95]}) print("profile →", r.content[0].text[:240], "...\n") # 4) Correlación r = await s.call_tool("correlation", {"method":"pearson"}) print("correlation →", r.content[0].text[:240], "...\n") asyncio.run(main()) PY

Estructura del proyecto

src/ dataframe_analyst_mcp/ __init__.py server.py # FastMCP app (herramientas declaradas) state.py # almacena el DataFrame en memoria de sesión tools/ __init__.py loader.py schema.py missing.py profile.py corr.py outliers.py groupby.py export_report.py examples/ ventas_2023.csv ventas_2023.xlsx demo_script.md out/ # (se crea al exportar reportes locales) secrets/ # credenciales (ignorar en git) pyproject.toml README.md

Solución de problemas

No se encuentra el módulo: ejecuta python -m pip install -e . en la raíz del repo y verifica que src/ contenga dataframe_analyst_mcp/.
Importa pero no conecta por STDIO: prueba PYTHONPATH=src python -m dataframe_analyst_mcp.server --mcp.
403/404 en Drive/Sheets: comparte recursos con el correo de la Service Account o usa OAuth Desktop (ver arriba).
xlrd: solo es compatible xlrd==1.2.0. Para .xlsx usa openpyxl.
Correlación con 0s: las columnas no numéricas se muestran como 0; limita a numéricas si lo deseas en tu reporte.

DataFrame Analyst MCP