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 (
patha CSV/XLS/XLSX). - Google Drive (fileId).
- Google Sheets (spreadsheetId + range/sheet opcional).
- Local (
- 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,wheelactualizados.
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.0se requiere solo para .xls antiguos. Para .xlsx se usaopenpyxl.
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 quesrc/contengadataframe_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).
xlrdy archivos.xls: solo es compatiblexlrd==1.2.0. Para.xlsxusaopenpyxl.- Correlación con 0s: las columnas no numéricas se muestran como 0; limita a numéricas si lo deseas en tu reporte.