MCP Excel Académico
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCP Excel Académico
Servidor MCP (Model Context Protocol) en TypeScript que da a un asistente de IA tres herramientas para trabajar con planillas de cálculo locales: inspeccionarlas, limpiar filas incompletas y generar un resumen estadístico. Está pensado para docencia e investigación académica y funciona con opencode, Claude Desktop, Cursor o cualquier cliente MCP por stdio.
1. Descripción y problema académico
En trabajos de laboratorio, estadística o investigación clínica es habitual recibir un Excel con:
celdas vacías que distorsionan promedios y conteos;
hojas con decenas de columnas cuyo significado no está documentado;
la necesidad de repetir a mano la misma limpieza y el mismo resumen para cada entrega.
Hacerlo manualmente es lento y difícil de reproducir: dos personas pueden obtener resultados distintos aplicando criterios diferentes. Este MCP convierte esas tres tareas en herramientas explícitas, con parámetros validados y resultados verificables, para que el asistente pueda ayudar sin editar el archivo "a ciegas". Los datos se procesan localmente, sin subirlos a ningún servicio externo.
El flujo recomendado es siempre: inspeccionar → limpiar → resumir.
Related MCP server: Excel MCP Server
2. Requisitos
Node.js 18 o superior y
npm(vernode --version).Un cliente MCP: opencode (recomendado), Claude Desktop, Cursor o el MCP Inspector.
Un archivo de datos local (en este repo,
datos_ejemplo.xlsx).No hace falta tener Microsoft Excel instalado: la lectura y escritura se hacen con la librería
xlsx(SheetJS).
Funciona en Windows, macOS y Linux. En Windows, si PowerShell bloquea npm.ps1 por su política de scripts, usa npm.cmd en todos los comandos.
3. Instalación paso a paso
git clone https://github.com/Maurichilean3d/mcp-starter-kit.git mcp-excel-academico
cd mcp-excel-academico
npm install
npm run build
npm testnpm test compila el código y ejecuta la prueba de humo; debe terminar con Prueba de humo superada. y listar las siete herramientas (las cuatro de la plantilla más las tres de Excel).
Después:
Abre tu cliente MCP en esa misma carpeta (
opencode).El archivo
opencode.jsonya registra el servidor; reinicia el cliente si ya estaba abierto antes de compilar.Para probar sin conexión, ejecuta
npm run inspecty llama a las herramientas desde el Inspector.
Si quieres volver a generar el archivo de ejemplo original (esto sobrescribe datos_ejemplo.xlsx):
node scripts/crear-datos-ejemplo.mjs4. Archivo de ejemplo
datos_ejemplo.xlsx contiene datos clínicos ficticios de laboratorio:
Hoja | Contenido |
| 20 registros, 13 columnas (identificador, fecha, género, edad, hemoglobina, hematocrito, leucocitos, plaquetas, glucosa, creatinina, sodio, potasio y diagnóstico). Tiene 7 celdas vacías repartidas en género, edad, plaquetas, glucosa, sodio y potasio. |
| Rangos de referencia de los análisis. |
Al ejecutar las herramientas se añaden Datos_Limpios (13 filas sin celdas vacías) y Resumen_Estadistico (9 columnas numéricas).
5. Herramientas propias
Herramienta | Qué hace | Escritura |
| Lee y describe la estructura de una hoja. | No (solo lectura) |
| Elimina filas con celdas vacías, con filtro opcional, y guarda el resultado en | Sí: exige |
| Calcula estadística descriptiva y la guarda en | Sí: exige |
Las rutas se resuelven y validan antes de abrir el archivo; solo se aceptan extensiones .xlsx, .xlsm y .xls.
5.1. excel_inspeccionar
Devuelve: hojas del libro, hoja inspeccionada, columnas, total de filas, primeras 5 filas y cantidad de celdas vacías por columna. Úsala siempre antes de las otras dos.
Parámetros
archivo(obligatorio): ruta al archivo Excel.hoja(opcional): nombre de la hoja; por defecto, la primera (Laboratorio).
Ejemplo en lenguaje natural
"Inspecciona datos_ejemplo.xlsx y dime qué columnas tienen datos incompletos."
Ejemplo de llamada
{
"archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx"
}Resultado esperado (extracto)
{
"hojas": ["Laboratorio", "Referencias"],
"columnas": ["id_paciente", "fecha_muestra", "genero", "edad", "..."],
"total_filas": 20,
"celdas_vacias_por_columna": { "genero": 1, "edad": 1, "glucosa_mg_dL": 2 }
}5.2. excel_limpiar_datos
Elimina todas las filas que tengan al menos una celda vacía. Opcionalmente filtra por una columna y un valor (comparación exacta, sin distinguir mayúsculas). Guarda el resultado en la hoja Datos_Limpios del mismo archivo, conservando la hoja original. Si la hoja destino ya existe, se sobrescribe.
Parámetros
archivo(obligatorio): ruta al archivo Excel.hoja(opcional): hoja de origen; por defecto, la primera.columnayvalor(opcionales, deben ir juntos): filtro a aplicar.confirmar(obligatorio): literaltruepara autorizar la escritura.
Ejemplo en lenguaje natural
"Limpia los datos incompletos de datos_ejemplo.xlsx y guárdalos en una hoja nueva; confirma la escritura."
Ejemplo de llamada
{
"archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx",
"confirmar": true
}Para quedarse solo con las filas completas de un diagnóstico:
{
"archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx",
"columna": "diagnostico",
"valor": "Diabetes tipo 2",
"confirmar": true
}Resultado esperado (extracto)
{
"hoja_destino": "Datos_Limpios",
"filas_originales": 20,
"filas_eliminadas": 7,
"filas_guardadas": 13,
"filtro": null
}5.3. excel_resumen_estadistico
Para cada columna cuyos valores no vacíos sean todos numéricos calcula: conteo, promedio, desviacion_estandar, minimo y maximo. La desviación es muestral (denominador n - 1) y los resultados se redondean a 4 decimales. Escribe una hoja Resumen_Estadistico con columnas Columna, Conteo, Promedio, Desviacion_Estandar, Minimo y Maximo.
Parámetros
archivo(obligatorio): ruta al archivo Excel.hoja(opcional): hoja a analizar; por defecto, la primera. Para analizar los datos ya limpios, indica"Datos_Limpios".confirmar(obligatorio): literaltruepara autorizar la escritura.
Ejemplo en lenguaje natural
"Genera el resumen estadístico de la hoja Datos_Limpios de datos_ejemplo.xlsx y confírmalo."
Ejemplo de llamada
{
"archivo": "C:\\mcp-excel-academico\\datos_ejemplo.xlsx",
"hoja": "Datos_Limpios",
"confirmar": true
}Resultado esperado (extracto)
{
"columnas_numericas": 9,
"estadisticas": [
{
"columna": "hemoglobina_g_dL",
"conteo": 13,
"promedio": 13.05,
"desviacion_estandar": 1.27,
"minimo": 10.8,
"maximo": 15
}
]
}Los valores del extracto son ilustrativos; ejecuta la herramienta para obtener los cálculos reales sobre la hoja que elijas.
6. Responsabilidad, Seguridad y Límites conocidos
Permisos y privacidad
El MCP solo accede a archivos locales cuya ruta proporciona el usuario; no abre conexiones de red ni envía datos a servicios externos.
La validación de extensión admite actualmente
.xlsx,.xlsmy.xls..csvforma parte del alcance previsto de la política de permisos, pero todavía no está implementado: intentar usarlo devuelve un error controlado. No documents.csvcomo soportado hasta añadirlo al validador desrc/lib/excel.ts.No se usan claves de API ni secretos en el código.
Los datos de
datos_ejemplo.xlsxson ficticios. Para datos reales de personas, anonimízalos y verifica que tienes autorización para procesarlos; este MCP no sustituye una revisión ética ni normativa.
Confirmación y writing
excel_limpiar_datosyexcel_resumen_estadisticodeclarandestructiveHint: truey exigenconfirmar: true. Sin ese literal, devuelven un error y no tocan el archivo.Ambas escriben dentro del mismo libro y sobrescriben
Datos_Limpios/Resumen_Estadisticosi ya existen. No hay papelera, historial niundo: haz una copia antes de ejecutarlas sobre un archivo importante.La limpieza no elimina la hoja original; solo añade una hoja nueva. Aun así, revisa el resultado antes de usarlo como fuente oficial.
Límites conocidos
La primera fila se trata como encabezados; no se admiten tablas con encabezados en otra fila ni celdas combinadas complejas.
Las filas totalmente vacías se ignoran; una fila se considera incompleta si cualquier columna está vacía (no hay umbral configurable).
El filtro es de igualdad exacta (ignorando mayúsculas); no admite comodines, rangos ni expresiones regulares.
No se evalúan fórmulas: se leen los valores guardados en caché por Excel.
Una columna solo entra al resumen si todos sus valores no vacíos son numéricos o cadenas convertibles a número; las fechas y columnas mixtas se omiten.
La desviación estándar es muestral; para población completa hay que ajustar el denominador.
hojaselecciona una sola hoja por llamada; no se puede resumir el libro completo de una vez.Las extensiones
.xlsmy.xlspasan el validador pero solo.xlsxse usa en las pruebas; las macros no se ejecutan ni se conservan de forma garantizada.No hay límite de tamaño de archivo ni bloqueos concurrentes: evita abrir el mismo libro en Excel mientras se escribe desde el MCP.
Uso de IA generativa
Este proyecto fue desarrollado con asistencia de IA generativa (opencode junto a un modelo de lenguaje) para redactar el código, las descripciones de las herramientas y esta documentación. El resultado fue compilado (npm run build), probado (npm test) y verificado manualmente ejecutando las tres herramientas sobre datos_ejemplo.xlsx. La IA es una herramienta de apoyo: las decisiones sobre qué datos limpiar, qué archivos autorizar y cómo interpretar los resultados son responsabilidad de quien usa el MCP.
7. Estructura relevante
src/index.ts Arranque; carga automática de src/tools/
src/tools/excel.ts Las 3 herramientas de Excel
src/lib/excel.ts Validación de rutas, lectura/escritura y helpers
scripts/crear-datos-ejemplo.mjs Generador del archivo de ejemplo
scripts/smoke-test.mjs Prueba de humo del servidor
datos_ejemplo.xlsx Libro de práctica
opencode.json Registro del MCP en opencode
docs/, AGENTS.md Guías y reglas de la plantilla original8. Comandos útiles
Comando | Qué hace |
| Instala dependencias (incluye |
| Compila TypeScript a |
| Compila y verifica handshake, listado y ejecución de herramientas. |
| Abre el MCP Inspector para probar las herramientas con interfaz visual. |
| Recrea el Excel de ejemplo desde cero. |
Licencia
MIT. Proyecto derivado de la plantilla mcp-starter-kit; conserva las herramientas de ejemplo hora_actual, saludar, listar_aplicaciones y abrir_aplicacion.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
The Excel engine for AI agents: read, check and edit Excel models over MCP.
Clean messy tabular data and render publication-ready PNG charts from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to read, write, and manipulate Excel files through comprehensive spreadsheet operations. Supports file management, data querying, worksheet operations, formula calculations, and includes security features like path validation and automatic backups.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create, read, write, and manipulate Excel files (.xlsx, .xlsm) without requiring Microsoft Excel, including support for charts, pivot tables, data import/export, and professional formatting across Windows, macOS, and Linux.143 npm35MIT
- AlicenseNot gradedqualityDmaintenanceEnables manipulation of Excel files including creating, reading, writing data, formatting, charts, pivot tables, and worksheet management via natural language.12 npmMIT
- AlicenseAqualityDmaintenanceEnables AI assistants to read and write local Excel and CSV files, supporting editing, styling, and image insertion.15MIT