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 y archivos .xls: 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