logisheets-mcp

Un motor de hojas de cálculo real en el que tu agente de IA puede pensar.

Un servidor MCP que le da a cualquier agente LLM un motor de cálculo real compatible con Excel, con memoria estructurada a la que puede dirigirse semánticamente, y un .xlsx de verdad al final que un humano puede abrir, auditar y seguir usando.

Construido sobre LogiSheets, un motor de hojas de cálculo escrito en Rust. Con licencia MIT, autoalojable, sin dependencia de la nube.

Por qué

Los agentes están haciendo trabajo real con forma de hoja de cálculo — modelos financieros, conciliación de datos, análisis — y son malos exactamente en las partes en las que un motor de hojas de cálculo es bueno.

Aritmética. Los agentes suman y multiplican mal. Aquí no tienen que hacerlo: escriben una fórmula y un motor determinista la evalúa.

Memoria. A lo largo de una tarea de treinta pasos, el estado intermedio tiene que vivir en algún sitio estructurado. Una ventana de contexto es costosa y pierde información; las variables de un sandbox de código desaparecen. Este servidor le da al agente un disco estructurado externo que lee y escribe durante toda la tarea.

Direccionamiento. Los agentes son malos en el razonamiento espacial, así que una cuadrícula en bruto es una superficie frágil — pierden la noción de dónde están las cosas, y sus propias ediciones rompen sus referencias. Así que el agente no se dirige a C7. Se dirige a (bloque, clave_fila, campo):

establece el campo price del registro 2025 en el bloque revenue

Inserta una fila, mueve el bloque, añade una columna — esa dirección sigue resolviéndose. Este es el punto central: memoria que sobrevive a las propias ediciones del agente.

Frente a un sandbox de Python

Un intérprete de código puede calcular, pero obtienes un resultado de script desechable. Aquí obtienes un .xlsx real con fórmulas vivas todavía dentro — ábrelo en Excel, cambia un dato de entrada, y el modelo recalcula. Hace el viaje de ida y vuelta con los archivos existentes del humano, y se ejecuta en tu máquina, lo cual importa cuando los datos no pueden salir.

Related MCP server: Excel MCP Server

Instalación

Requiere Node 20+.

npm install -g logisheets-mcp

Claude Desktop

Añade a claude_desktop_config.json:

{
    "mcpServers": {
        "logisheets": {
            "command": "npx",
            "args": ["-y", "logisheets-mcp"]
        }
    }
}

En macOS ese archivo vive en ~/Library/Application Support/Claude/claude_desktop_config.json; en Windows, %APPDATA%\Claude\claude_desktop_config.json. Reinicia Claude Desktop después.

Cursor / Cline / otros hosts

Cualquier host MCP que pueda lanzar un servidor stdio funciona — apúntalo al comando logisheets-mcp. Para Cursor, añade el mismo bloque a ~/.cursor/mcp.json.

Pruébalo

Construye un modelo de ingresos a tres años: 100 unidades a $9.50 creciendo un 40% al año, con un 30% de coste de mercancías. Luego guárdalo en ~/model.xlsx.

El agente crea un bloque, lo rellena, escribe las fórmulas y te devuelve un archivo. Los números son del motor, no conjeturas del modelo — y el .xlsx tiene fórmulas reales, así que puedes cambiar una hipótesis en Excel y ver cómo recalcula.

Verlo funcionar

npm run build && npm run demo

Construye un pequeño modelo de ingresos sobre MCP real sobre stdio contra dist/cli.js — el mismo camino de código que usa Claude Desktop — y comprueba cada afirmación sobre la marcha: totales que calculó el motor, una regla que alcanza filas añadidas después, bloques que siguen resolviendo cuando el modelo crece por debajo, y un .xlsx real cuyas fórmulas se verifican leyendo los propios bytes del archivo. No interviene ningún LLM; el motor es el sujeto, y codificar las llamadas es lo que hace que las garantías sean comprobables en lugar de una historia sobre una sesión de chat.

El bucle del agente

list_blocks                     orient: what do I have?
create_block                    open a structured workspace
add_block_rows / set_block_cells    fill it, addressed by (block, key, field)
eval_formula / a stored formula      the engine does the math
describe_block                  read structured results back
save_workbook                   hand the human a real .xlsx

Herramientas

La superficie por defecto es deliberadamente pequeña — 20 herramientas. La precisión de la selección de herramientas cae a medida que la lista crece, y cada descripción cuesta contexto en cada turno.

Las fórmulas son compatibles con Excel, más BLOCKREF(bloque, clave, campo) para leer una celda de bloque semánticamente. Dentro de una regla de campo, #FIELD("nombre") es el hermano de la misma fila y #FIELD("nombre", "clave") es otra fila del mismo bloque — la que lleva esa clave, nunca un desplazamiento posicional, así que reordenar filas no puede cambiar lo que significa una fórmula.

Analizar un modelo, no solo construirlo

preview_changes toma una lista de scenarios y un watch opcional, que es lo que convierte la exploración de docenas de viajes de ida y vuelta en uno solo:

{
  "scenarios": [
    {"label": "wacc 9%",  "changes": [{"block":"assum","row_key":"wacc","field":"v","value":0.09}]},
    {"label": "wacc 12%", "changes": [{"block":"assum","row_key":"wacc","field":"v","value":0.12}]}
  ],
  "watch": [{"block":"valuation","row_key":"per_share","field":"v"}]
}

Cada escenario se ejecuta en su propia rama temporal y se descarta, así que el modelo vivo nunca se toca — sin mutar-y-revertir, y sin dejar nada atrás si un escaneo falla a mitad. Una cuadrícula de sensibilidad de 4×4 es una llamada que devuelve dieciséis números.

goal_seek hace el mismo truco al revés — "qué tasa de descuento da un valor por acción de 30" — con la búsqueda dentro del motor en lugar de como conversación, así que es una llamada en lugar de una por paso de bisección. Dice cuándo un objetivo simplemente no es alcanzable en el intervalo en lugar de devolver el número más cercano en el que se detuvo.

trace responde las dos preguntas de auditoría desde el grafo de dependencias del motor: qué lee una celda, y qué la lee. La segunda es por lo que existe — el texto de la fórmula se puede leer hacia adelante pero no hacia atrás, y "qué se rompe si cambio esto" es la pregunta que quieres antes de tocar una hipótesis.

Leer un modelo también es semántico: describe_block devuelve la regla de cada campo, así que un agente aprende la lógica del modelo sin visitar una celda, y las fórmulas vuelven nombrando lo que leen (B24 / BLOCKREF("assum","shares","v")) en lugar de como cadenas de coordenadas que tienes que perseguir.

La superficie completa

Establece LOGISHEETS_MCP_TOOLS=full para 50 herramientas: deshacer/rehacer, formato de celdas, fusiones, comentarios, puntos de control, mover/redimensionar bloques, enlaces entre bloques y estructura bruta de filas/columnas.

{
    "mcpServers": {
        "logisheets": {
            "command": "npx",
            "args": ["-y", "logisheets-mcp"],
            "env": {"LOGISHEETS_MCP_TOOLS": "full"}
        }
    }
}

Las herramientas de mutación están marcadas con las anotaciones readOnlyHint / destructiveHint de MCP, así que un host puede ponerlas detrás de la aprobación del usuario.

Bloques, en breve

Un bloque es una región con nombre y estructura de una hoja — una tabla con un esquema.

• El primer campo es la clave de fila: el nombre estable de cada registro.

• Los campos pueden llevar una fórmula de valor (calculada por el motor, así que el agente no puede escribir un número obsoleto en ella), una regla de validación o una regla de editabilidad.

• Todo se dirige por nombre. Los índices de fila y columna nunca entran en el razonamiento del agente.

Como los bloques se crean por el agente mientras trabaja, esto no necesita un archivo preparado — puedes apuntarlo a un libro en blanco o a una hoja de cálculo que alguien te haya enviado.

Usar como biblioteca

import {createServer} from 'logisheets-mcp'
import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js'

const {server, session} = createServer({mode: 'full'})
await server.connect(new StreamableHTTPServerTransport(/* … */))

createServer devuelve el Server de MCP, el WorkbookSession y el mapa de herramientas, así que puedes alojarlo sobre cualquier transporte o incrustarlo en un framework de agentes.

Desarrollo

El servidor es una capa fina sobre tres paquetes de LogiSheets: logisheets-runtime (el motor sin interfaz), logisheets-logician (las definiciones de herramientas del agente) y el núcleo Rust/WASM. Trabajar solo en el servidor no necesita nada especial:

git clone https://github.com/logisky/logisheets-mcp.git
cd logisheets-mcp
npm install
npm test

Trabajar en el motor al mismo tiempo es el otro modo. Clona LogiSheets como directorio hermano, construye sus paquetes y luego:

npm run link:local     # re-run after any npm install

Eso crea enlaces simbólicos de los tres paquetes en node_modules para que los cambios locales del motor surtan efecto sin reinstalar. scripts/release-deps.mjs restaura los rangos del registro antes de publicar.

Publicar

Una etiqueta lo hace. .github/workflows/publish.yaml ejecuta las pruebas, publica en npm con procedencia y registra la nueva versión en el Registro MCP:

npm version 0.2.0        # bumps both files, commits, tags v0.2.0
npm run check-release    # optional; CI runs it too
git push --follow-tags

El flujo de trabajo también se puede ejecutar a mano desde la pestaña Actions, que toma la versión de package.json en lugar de una etiqueta. El paso de npm omite una versión que ya está publicada, así que una ejecución que falló en el paso del registro se puede simplemente re-ejecutar — las dos publicaciones no son una transacción.

npm version también reescribe server.json, mediante el script de ciclo de vida version. El registro mantiene la versión en dos sitios — la version del propio servidor y la versión del paquete npm al que apunta — y editarlos a mano es el paso que más probablemente se olvide.

check-release es la puerta. Cuatro cosas tienen que coincidir: la etiqueta, package.json y ambos campos de versión de server.json. mcpName también tiene que ser igual al name de server.json, porque el registro demuestra la propiedad leyendo mcpName del paquete npm publicado. npm publish no se puede deshacer — un número de versión se gasta en el momento en que llega — así que el flujo de trabajo ejecuta esta comprobación antes de publicar, no después.

La autenticación del registro no necesita secreto: el flujo de trabajo se autentica con GitHub OIDC, que es lo que concede el espacio de nombres io.github.logisky/. El único secreto es NPM_TOKEN.

Recuperar el archivo

save_workbook escribe un .xlsx real y su resultado lleva un enlace de recurso MCP — un uri, tipo de medio y tamaño — no el archivo. El libro también se lista como recurso (workbook://current.xlsx), así que un host que quiera los bytes los lee con resources/read y le da al humano una descarga.

Esa división es el punto: un resultado de herramienta va al contexto del modelo, donde un libro de 200 KB costaría unos 280 KB de texto y no le enseñaría nada al modelo. El enlace cuesta una línea. export_xlsx sigue devolviendo base64 para hosts que no implementan recursos, pero es el plan B, no el mecanismo.

Las lecturas pasan por el mismo carril de serialización que las llamadas a herramientas, así que un host que obtiene el archivo nunca puede atrapar una transacción a medio aplicar.

open_workbook y save_workbook leen y escriben dondequiera que el proceso del servidor pueda — normal para un servidor stdio local, y la misma postura que el servidor de sistema de archivos oficial. Ambos están marcados como mutantes para que un host pueda pedir confirmación antes de que se ejecuten; si necesitas límites más estrictos, ejecuta el servidor como un usuario con solo el acceso que pretendes que tenga.

Modelo de estado

Una sesión de MCP mantiene un libro de trabajo activo, vivo a través de las llamadas a herramientas — esa persistencia es lo que lo convierte en memoria en lugar de una calculadora. open_workbook lo reemplaza. Puede que más adelante haya varios libros de trabajo con nombre por sesión.

Sin red

El servidor no abre sockets ni escucha en ningún puerto. El «transporte stdio» es literal: tu host de MCP lo lanza como proceso hijo y ambos intercambian JSON-RPC delimitado por saltos de línea a través de su stdin y stdout — las mismas tuberías que recibe cualquier programa de línea de comandos. El motor es WASM que se ejecuta en ese mismo proceso, así que una fórmula es una llamada a función, no una petición.

Comprobado en lugar de afirmado. Tras una sesión completa — crear un bloque, adjuntar una regla de campo, evaluar una fórmula, guardar un .xlsx — el proceso contiene:

fd types: {CHR: 2, DIR: 4, KQUEUE: 3, PIPE: 6, REG: 13}
network files (lsof -a -i):     0
unix sockets  (lsof -a -U):     0
listening ports:                0

Seis tuberías, ningún socket. No se sube nada, no se recopila telemetría, y una máquina aislada de la red es una forma compatible de ejecutar esto. Lo único que toca fuera de su propia memoria son los archivos que nombres — consulta la nota sobre el sistema de archivos en Cómo recuperar el archivo.

Ese es el binario logisheets-mcp, que es lo que ejecuta un host de MCP. Usándolo como biblioteca puedes adjuntar cualquier transporte que quieras, incluido uno HTTP — pero entonces el socket es tuyo, abierto deliberadamente.

Licencia

MIT. Parte del proyecto LogiSheets.