ExcelMCP

Una capa de inteligencia de Excel en vivo para agentes de IA. Apúntalo a una carpeta de OneDrive y tu agente podrá hacer preguntas sobre esas hojas de cálculo en lenguaje natural, con los números que contienen en ese momento.

El problema que resuelve esto

La mayoría de las integraciones de hojas de cálculo funcionan copiando tus datos a otro lugar. Ingieren el libro de trabajo, lo fragmentan, incrustan los valores de las celdas y almacenan todo en una base de datos vectorial. A partir de ese momento, tu agente responde preguntas sobre una instantánea. Alguien actualiza la hoja de inventario a las 9 de la mañana y el agente sigue citando los números del martes.

ExcelMCP divide el problema en dos.

La estructura se almacena en caché. Nombres de archivos, nombres de hojas, encabezados de columnas, dónde comienza la fila de encabezados, qué columnas contienen fechas, cómo se relacionan las hojas entre sí — además de una pequeña muestra de etiquetas distintas por columna de baja cardinalidad, que es lo que permite que el enrutamiento funcione en cien hojas casi idénticas. Esto cambia raramente, es barato de almacenar y es lo que el agente necesita para saber qué pedir. (Las etiquetas muestreadas son el único lugar donde la estructura toca los valores; el límite exacto se detalla en Qué cae en el disco.)

Los datos nunca se almacenan en caché. Cada llamada a una herramienta que devuelve un número sale a la API de Microsoft Graph y la obtiene en vivo. No hay caché de datos que se vuelva obsoleta, ni trabajo de sincronización que se retrase, ni respuesta que se sirva desde el disco.

Cada respuesta lleva una marca de tiempo metadata.fetched_at y una bandera is_cached: false para que el modelo pueda ver, en banda, que está mirando datos frescos.

Related MCP server: Microsoft 365 MCP Server

Cómo funciona

Una pregunta en lenguaje natural se incrusta, se compara con las descripciones de las hojas por similitud de coseno, y luego se reordena por superposición léxica con nombres de columna y valores muestreados — lo que mantiene el enrutamiento significativo cuando veinte libros de trabajo comparten un esquema. Esas hojas, y solo esas, se obtienen en vivo. El filtrado y la agregación se realizan luego en pandas sobre el marco recién obtenido. Las preguntas de un solo valor omiten la canalización de filas por completo: lookup lee una columna clave y una fila y devuelve la celda con su procedencia.

Requisitos

• Python 3.10 o más reciente

• Una cuenta de Microsoft 365 con OneDrive

• uv, o pip simple si lo prefieres

Instalación

Desde la raíz del repositorio:

git clone https://github.com/Karunya-Muddana/ExcelMCP.git
cd ExcelMCP

uv sync      # install dependencies
uv build     # build the wheel
pip install dist/excelmcp-0.3.0-py3-none-any.whl

O instala directamente desde la fuente sin construir:

pip install .

No hay paso de compilación ni extensión nativa que construir. La búsqueda vectorial se ejecuta en un escaneo de coseno de NumPy en lugar de hnswlib, específicamente para que pip install funcione en una máquina sin cadena de herramientas de C++.

Configuración

Ejecuta el asistente una vez:

excelmcp-setup

Recorre cuatro cosas:

1. Inicio de sesión de flujo de dispositivo de Microsoft. Obtienes un código, lo pegas en el navegador, la caché de tokens se guarda en ~/.excelmcp/token.json con permisos 0600.

2. Qué carpeta de OneDrive indexar, por ejemplo /ERP.

3. Un escaneo de cada .xlsx en esa carpeta para construir el grafo de estructura y las incrustaciones.

4. Detección de los agentes de IA ya instalados en tu máquina, y una entrada de configuración escrita para los que elijas.

Agentes que puede configurar automáticamente

Los archivos de configuración existentes se respaldan antes de ser modificados. Si tu agente no está en la lista, el asistente imprime el bloque exacto de JSON o TOML para que lo pegues tú mismo.

Otros comandos del asistente

excelmcp-setup list-agents           # show what was detected
excelmcp-setup install --only cursor # register with one agent, skip the rescan
excelmcp-setup doctor                # diagnose a broken install
excelmcp-setup uninstall             # remove ExcelMCP from every agent config
excelmcp-setup --folder /ERP --yes   # fully non-interactive
excelmcp-setup --dry-run             # print the changes, write nothing

Herramientas expuestas al agente

Las dos herramientas de estructura son gratuitas e instantáneas porque leen el grafo local. Todo lo marcado como en vivo va a la API en cada llamada.

Uso

Una vez que el servidor está registrado, principalmente solo hablas con tu agente con normalidad. Internamente, realiza llamadas como estas.

Orientarse primero. El agente siempre debería hacer esto antes de adivinar un nombre de columna, ya que dos empresas no nombran las cosas de la misma manera:

get_workspace_graph(folder_path="/ERP")

Hacer una pregunta sin saber dónde está la respuesta:

query("what are the top 10 products by sales value", folder_path="/ERP")

Filtrar una hoja conocida:

filter_sheet(
    file_name="Inventory.xlsx",
    sheet="Stock",
    conditions={"Status": "Low", "Quantity": "<50"},
    folder_path="/ERP",
    sort_by="Quantity",
    limit=100,
)

Operadores de condición admitidos, todos ANDeados:

Un nombre de columna u operador que no existe genera un error en lugar de devolver silenciosamente cero filas, que es el modo de fallo que hace que un agente informe con confianza lo incorrecto. Cuando las condiciones legítimamente no coinciden con nada, la respuesta lleva zero_match_diagnostics — qué coincidió cada condición por sí sola, más hasta veinte valores realmente presentes en la columna problemática — para que un casi acierto sea corregido en lugar de informarse como "sin datos".

Pedir una sola cifra en una llamada:

lookup(query="contracted rate for Titanium Dioxide under the BESTEX contract",
       folder_path="/Contracts")

La respuesta viene con procedencia — archivo, hoja, dirección de celda, la fila coincidente — y un campo de confianza. Múltiples filas coincidentes devuelven ambiguous con cada fila; las hojas que no coinciden devuelven conflict con cada versión y sin valor; una clave mal escrita devuelve sugerencias difusas. La herramienta nunca devuelve un número desnudo.

Agrupar y reducir dentro de un archivo:

aggregate(
    file_name="Sales.xlsx",
    sheet="Q1",
    group_by="Region",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
)

Totalizar la misma hoja en todos los archivos del espacio de trabajo:

cross_file_aggregate(
    sheet="Q1",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
    conditions={"Status": "Closed"},
)

cross_file_aggregate devuelve un desglose por archivo junto con el total, más skipped_files cuando un archivo no pudo ser leído y unmatched_files — con candidatos did_you_mean — para cada archivo que no contiene el nombre exacto de la hoja. De esta manera, un total parcial es visiblemente parcial en lugar de estar silenciosamente equivocado, incluyendo el caso donde la hoja se llama Sales en algunos archivos y Sales 2024 en otros. Consulta sheet_name_variants en get_workspace_graph antes de agregar para ver esa fragmentación de antemano.

Manual del agente

Tener el servidor instalado es la mitad fácil. La carpeta agents/ cubre la otra mitad: cómo incitar a un agente que tiene estas herramientas, cómo conectarlo en cada anfitrión, y qué automatizar una vez que funciona.

Salvaguardas integradas en el servidor

El servidor incluye un conjunto de reglas operativas en sus instrucciones MCP, que el modelo anfitrión lee antes de realizar su primera llamada. Existen porque estas son las formas específicas en que un LLM falla en preguntas sobre hojas de cálculo:

• Nunca asumas un nombre de archivo, un nombre de hoja o un nombre de columna. Descúbrelo a partir del grafo.

• Nunca sumes números de varios archivos mentalmente. Llama a cross_file_aggregate y deja que la herramienta lo haga.

• Nunca recurras a openpyxl, pandas.read_excel ni al sistema de archivos local. Los archivos no están en esta máquina.

• Nunca sumes en bruto una columna de cantidad en datos de tipo transacción: usa derive con los tipos de transacción especificados.

• Las columnas de fecha llegan como cadenas ISO-8601, ya convertidas de seriales por el servidor. Nunca hagas aritmética de seriales a mano.

• Para una cifra única, llama a lookup y cita la procedencia que devuelve; saca a la luz sus resultados ambiguous y conflict en lugar de elegir un valor.

• Comprueba los campos truncated y total_matched antes de afirmar que un resultado está completo.

Los hosts que ignoran las instrucciones del servidor, y los agentes personalizados que construyas tú mismo, necesitan que esto se indique en su propia indicación. Ver agents/system-prompt.md.

Configuración

El ID de cliente integrado es un cliente público utilizado para el flujo de código de dispositivo. No contiene ningún secreto, es visible en cada solicitud de autenticación por diseño y es seguro tenerlo en este repositorio. Cámbialo por tu propio registro de aplicación si quieres que la pantalla de consentimiento muestre el nombre de tu organización.

Qué se guarda en el disco

~/.excelmcp/
  token.json           MSAL token cache. Auth material only, written 0600.
  graph.json           Structure graph: item IDs, sheet names, column headers,
                       used-range dimensions, date column types, per-sheet
                       table regions, inferred and formula-declared
                       relationships — and sampled values (see below).
  vectors.npy          Embedded sheet descriptions for semantic routing.
  metadata.json        Labels and lexical terms tying each embedding to a sheet.
  relationships.yaml   Optional, written by you: declared join relationships.

La versión honesta de la afirmación de no caché, a partir de 0.3.0. Ninguna fila de tus datos, ninguna cuadrícula de celdas ni ningún valor consultable se almacena en disco: cada respuesta se sirve desde una obtención en vivo, siempre. Hay una excepción deliberada: graph.json almacena valores muestreados, hasta 50 etiquetas de texto distintas por columna de baja cardinalidad (nombres de clientes, estados, nombres de materiales, unidades), capturadas en el momento del escaneo. Existen para que cien hojas estructuralmente idénticas sean distinguibles al enrutar una pregunta, para que lookup pueda encontrar qué hoja contiene "BESTEX" sin descargarlo todo, y para que las relaciones puedan inferirse a partir de la superposición de valores en lugar de asumirse por los nombres de columna. Son evidencia de enrutamiento, no una caché de datos: nada responde nunca a una pregunta a partir de ellos, y un escaneo del espacio de trabajo los refresca por completo. El grafo también almacena una huella estructural por hoja (columnas de encabezado y dirección del rango usado) puramente para detectar desviaciones y, nuevo en 0.3.0, un mapa de regiones: los intervalos de filas de cada cuerpo de tabla en una hoja, derivados de los rangos a los que se refieren las fórmulas SUM/COUNT/AVERAGE de la propia hoja, más las direcciones que lee cualquier fórmula entre hojas. Esos son números de fila y direcciones de celda, no contenidos; no se lee ningún valor para producirlos. La label de una región, cuando está presente, es la segunda excepción deliberada junto con los valores muestreados: unas pocas palabras leídas de la celda del banner de sección inmediatamente encima de una región ("NAPHTHALENE", "OLEUM 65%"), conservadas para que el modelo pueda nombrar qué tabla quiere decir en lugar de adivinarlo por los números de fila. Son metadatos estructurales que describen la disposición de la hoja, no datos de fila: la misma distinción que ya establecen los valores muestreados. Si algo de esto es más de lo que quieres en disco, no escanees esa carpeta; si quieres verificar el límite, graph.json es pequeño y legible, así que échale un vistazo.

En Windows, os.chmod solo alterna el bit de solo lectura, así que establecer el modo 0600 es lo máximo que se puede hacer allí, y la protección real es la ACL predeterminada por usuario en %USERPROFILE%. En macOS y Linux, el modo se aplica al archivo temporal antes de que se escriba cualquier contenido, por lo que el token nunca existe brevemente como legible por todos.

Tests

# offline unit tests, no network and no credentials required
pytest tests/test_unit.py

# live integration tests against a workspace you have already scanned, opt in
EXCELMCP_TEST_FOLDER=/ERP pytest tests/test_live_integration.py -v

La suite de integración se omite a sí misma cuando EXCELMCP_TEST_FOLDER no está definido, por lo que una ejecución simple de pytest permanece sin conexión.

Estructura del proyecto

agents/           prompts, host guides, and schedulable routines
auth.py           MSAL device flow, token cache, proactive refresh
graph_client.py   Graph API wrapper, 429 backoff, shared concurrency gate
structure.py      Structure discovery, value sampling, relationship inference
embeddings.py     FastEmbed vectors, NumPy cosine search, lexical rerank
query_engine.py   Conditions, live fetch, aggregation, joins, derive
lookup.py         Single-cell lookup pipeline and get_cell
ranges.py         A1-notation range arithmetic
main.py           FastMCP tool definitions and server entry point
cli.py            Setup wizard, agent detection, config writing
agents.py         Per agent config formats and file locations
storage.py        Atomic writes, stderr logging, config directory handling

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Si estás añadiendo soporte para otro agente, agents.py es el único archivo que deberías necesitar tocar: añade un AgentSpec con la ruta de configuración, la forma de entrada y una pista de detección.

Licencia

MIT. Ver LICENSE.