# Excel MCP Server

Servidores MCP locales que conectan Claude con archivos Excel .xlsx reales en tu disco. El objetivo es transformar la IA en un asistente de análisis financiero y operativo que puede leer, comparar, limpiar, reconciliar y escribir sobre Excel sin depender de la nube.

Este repositorio está pensado como un complemento del [MCP-Financial-Controller](https://github.com/alexhb-maker/MCP-Financial-Controller), Para Power bi, pero también funciona como proyecto independiente y totalmente útil por sí mismo.


## Qué hace este repo

El servidor Excel permite:

- inspeccionar archivos y hojas de Excel
- leer datos sin abrir Excel manualmente
- detectar duplicados, nulos y valores atípicos
- comparar dos archivos o dos hojas por clave
- consolidar varios Excel en uno solo
- escribir celdas, rangos y fórmulas reales
- recalcular fórmulas via Excel real con xlwings (opcional)

La idea es dejar de hacer tareas repetitivas a mano: comprobar balances, revisar conciliaciones, analizar exportaciones, comparar versiones mensuales, etc., todo desde Claude y un MCP local.

## Cómo se conecta al archivo Excel

El flujo es simple:

- Claude recibe la ruta completa del archivo Excel
- el servidor valida esa ruta
- lee la hoja deseada con pandas/openpyxl
- devuelve datos, insights o resultados estructurados
- si se escribe, guarda directamente el .xlsx real en el disco

Esto permite trabajar con archivos locales de contabilidad, extractos bancarios, cierres mensuales, conciliaciones, bases de clientes y mucho más.

## Qué incluye

La base funcional del servidor incluye:

- lectura de una hoja o de todas las hojas
- columnas, valores únicos, búsqueda por texto
- resumen estadístico y agregación
- calidad de datos y análisis financiero básico
- comparación y conciliación entre archivos
- escritura sobre celdas y rangos
- recálculo opcional de fórmulas con Excel real

El catálogo completo de herramientas está en:

- [docs/TOOLS_REFERENCE.md](docs/TOOLS_REFERENCE.md)
- [examples/EXAMPLES.md](examples/EXAMPLES.md)
- [docs/GUIA_MCP_EXCEL.txt](docs/GUIA_MCP_EXCEL.txt)

## Estructura del repositorio

```text
mcp-excel/
├── README.md
├── INSTALL.md
├── CONFIGURATION.md
├── LICENSE
├── requirements.txt
├── .gitignore
├── config/
│   └── claude_desktop_config.example.json
├── docs/
│   ├── TOOLS_REFERENCE.md
│   └── GUIA_MCP_EXCEL.txt
├── examples/
│   └── EXAMPLES.md
└── src/
    └── excel_server.py
```

## Quick start

1. Sigue la guía de instalación:

   - [INSTALL.md](INSTALL.md)

2. Instala dependencias:

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

3. Ejecuta el servidor:

```bash
python src/excel_server.py
```

4. Prueba algo sencillo:

```python
info_excel("C:/Data/demo.xlsx")
```

## Instalación y requisitos

Necesitas:

- Python 3.10+
- pandas
- numpy
- openpyxl
- mcp
- xlwings (opcional, para recálculo real)
- Excel instalado en tu PC (opcional, si quieres recalcular fórmulas reales)

Se puede consultar la guía completa en:

- [INSTALL.md](INSTALL.md)

## Configuración

Si quieres limitar el acceso a una carpeta concreta, define la variable de entorno:

```bash
EXCEL_MCP_BASE=C:\Data
```

Ejemplo de configuración MCP:

- [config/claude_desktop_config.example.json](config/claude_desktop_config.example.json)
- [CONFIGURATION.md](CONFIGURATION.md)

## Seguridad y buenas prácticas

- todo se ejecuta localmente en tu máquina
- favorece siempre una copia del archivo antes de escribir
- usa rutas controladas cuando trabajes con datos sensibles
- no compartas archivos de producción en repos públicos
- usa `EXCEL_MCP_BASE` si quieres restringir el acceso a un directorio concreto
- `recalcular()` solo funciona si Excel real y xlwings están disponibles

## Stack técnico

- Python
- FastMCP
- pandas
- openpyxl
- numpy
- xlwings (opcional)
- Excel local

## Roadmap

- mejorar validación y robustez de todas las herramientas
- añadir tests automatizados
- ampliar escritura y formateo de celdas
- incorporar validación de plantillas financieras típicas
- preparar más ejemplos de uso real con contabilidad y conciliación
- conectar este repo con el repo de Power BI en una capa de integración posterior

## About

Claude + Excel. Local MCP server for structured financial and operational analysis directly over .xlsx files.

## License

This project is licensed under the MIT License.

See [LICENSE](LICENSE) for details.