The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Siigo Pyme MCP listing page.
Servidor MCP que expone SIIGO Pyme a un agente de IA.
Envuelve EXCELSIIGO.exe, el ejecutable de interfases de SIIGO, y convierte sus 47 funciones
de exportación e importación en herramientas MCP con parámetros documentados, descubrimiento
automático de empresas y resultados ya parseados a JSON.
Se autodiagnostica: npx -y siigo-pyme-mcp --doctor dice si el equipo puede ejecutar SIIGO y qué
falta, y --print-config escupe el bloque de configuración exacto para su cliente MCP. Las dos
cosas funcionan antes de registrar nada.
| Requisito | Por qué |
|---|---|
| Windows | SIIGO Pyme solo existe en Windows. |
| SIIGO Pyme instalado | Se necesita EXCELSIIGO.exe (por defecto en C:\Siigo). |
| Microsoft Excel instalado | SIIGO genera los .xlsx con Excel por COM, a través de SiigoExcel.exe. Sin Excel no se produce ningún archivo. |
| Sesión de escritorio activa | Consecuencia de lo anterior: no funciona como servicio de Windows, ni por SSH sin sesión, ni en un contenedor. Durante cada ejecución verás aparecer la ventana de progreso de SIIGO y Excel: no se pueden ocultar, con la ventana oculta el proceso se cuelga sin generar nada. |
| Node.js 18 o superior | Para ejecutarlo con npx. |
No hace falta instalar nada: se ejecuta con npx. Cuatro pasos, y el propio paquete guía cada uno.
--print-config conoce hermes, Claude Desktop, Claude Code, VS Code y Cursor, e imprime
además los primitivos del protocolo para cualquier cliente que no esté en la lista. Sin argumento
--cliente los muestra todos. Para el caso genérico:
El -y no es opcional: sin él npx pide confirmación por consola, se queda esperando, y el
cliente MCP interpreta ese silencio como que el servidor no arrancó.
| Síntoma | Causa real |
|---|---|
npm error EBADPLATFORM ... wanted {"os":"win32"} | Se está instalando fuera de Windows (WSL, contenedor, Linux). Hay que registrarlo en la máquina Windows donde está SIIGO; --force no ayuda, porque sin SIIGO ni Excel no hay nada que ejecutar. |
| El cliente dice que el servidor no arrancó, sin más detalle | Falta el -y en npx. |
'npx' no se reconoce como un comando, o ENOENT al lanzarlo | El cliente MCP no tiene npx en su PATH. Use --print-config --absoluto, que emite un bloque apuntando a node.exe y al dist/index.js instalado, con las rutas reales de esa máquina. |
| Arranca, pero toda función falla sin generar archivo | Falta Excel, falta la sesión de escritorio, o alguna ruta pasa de 50 caracteres. Ejecute --doctor. |
En hermes hay un detalle que rompe la configuración escrita a mano: en su config.yaml, args y
env son cadenas JSON dentro del YAML, no una lista y un mapa YAML. --print-config --cliente hermes ya lo emite así.
Registrar el servidor no basta para que el agente sepa qué hacer con él. El "cómo usarme" vive en tres canales del protocolo MCP, y no todos los clientes los leen:
instructions del InitializeResult — el texto que este servidor manda al conectar.siigo://guia/inicio, siigo://protocolo) y el prompt siigo_puesta_en_marcha.En hermes, por ejemplo, el canal 1 se pierde por completo: captura el InitializeResult solo
para leer capabilities y nunca lee .instructions (tools/mcp_tool.py, en el comentario junto
a self.initialize_result). Los recursos y prompts del canal 2 son opt-in y ningún agente los
consulta espontáneamente. Solo queda el canal 3, así que este servidor lo usa a fondo:
siigo_start_here es la primera herramienta de tools/list, titulada "LEER PRIMERO", y
devuelve el protocolo de uso completo.siigo_* en
el proceso trae el protocolo anexado al final de su contenido, una sola vez.npx -y siigo-pyme-mcp --print-agent-rules --cliente <su cliente> imprime ese mismo
protocolo en el formato de reglas del cliente (una skill con frontmatter para hermes y Claude
Code, un bloque para pegar en AGENTS.md o las instrucciones del proyecto para el resto), para
que llegue antes de la primera llamada. Con --instalar lo escribe directamente en la
carpeta de skills del cliente (por ejemplo %LOCALAPPDATA%\hermes\skills\siigo-pyme-mcp\SKILL.md);
nunca sobrescribe un fichero existente con contenido distinto salvo que se agregue --forzar.siigo_doctor — verifica el entorno y dice qué falta. Es la primera llamada ante cualquier fallo.siigo_list_companies — lista las empresas SIIWI01..SIIWI99 disponibles.siigo_set_credentials — guarda usuario y clave. Sin indicar empresa, la credencial
se aplica a todas, que es lo más cómodo si usa el mismo usuario en todas ellas.siigo_describe_function — los parámetros exactos de la función que va a usar.siigo_run_function — ejecútela.El paso 4 no es ceremonia: el CLI acepta un parámetro mal formateado, lo registra como 081 y
termina con código 0, así que un error de parámetros se parece a un éxito. Es la única forma
en la que este servidor puede devolver datos equivocados.
HKLM\SOFTWARE\WOW6432Node\Informatica y Gestion S.A\Siigo Windows), de la configuración
del servidor, y escaneando las unidades en busca de carpetas <X>:\Siigo* que contengan
EXCELSIIGO.exe. Puede tener varias (C:\Siigo, C:\Siigo2, D:\Siigo...).filepath.txt la ruta de una empresa.
A partir de ella se explora la carpeta que la contiene buscando SIIWI00..SIIWI99. Solo
se aceptan las que traen datos reales de SIIGO (ZnnSIIGO, CONFIMP.CFG, archivos .DIS),
de modo que carpetas homónimas vacías o de instalación no se ofrecen como empresas.siigo_add_installation o
guarde credenciales directamente sobre la ruta de la empresa con siigo_set_credentials.Puede referirse a una empresa por su ruta (Z:\SIIWI01\), por su número (01) o por el alias.
Por defecto expone 12. Cada esquema de herramienta viaja en cada llamada al modelo, así que
las 47 funciones como herramientas independientes cuestan unos 35 000 tokens por llamada —
medidos: 140 116 caracteres de tools/list frente a 8 927 del perfil por defecto, un 94 % menos.
Se controla con SIIGO_TOOLS:
SIIGO_TOOLS | Herramientas | Coste de tools/list |
|---|---|---|
core (por defecto) | 12: las de apoyo más siigo_run_function | ~2 200 tokens |
all | 58: una por cada función | ~35 000 tokens |
| Herramienta | Para qué |
|---|---|
siigo_start_here | LEER PRIMERO: protocolo de uso completo. Primera de tools/list a propósito. |
siigo_doctor | Verifica Windows, SIIGO, Excel, sesión de escritorio, credenciales, empresas y el límite de 50 caracteres. No ejecuta nada de SIIGO. |
siigo_list_installations | Instalaciones de SIIGO detectadas. |
siigo_list_companies | Empresas disponibles, con alias y si tienen credenciales. |
siigo_list_functions | Catálogo de las 47 funciones, filtrable por grupo. |
siigo_describe_function | Parámetros, orden posicional y ejemplo del manual de una función. |
siigo_set_credentials | Guarda usuario y clave, global o por empresa. |
siigo_set_company_alias | Da un nombre legible a una empresa. |
siigo_add_installation | Registra una instalación que no se detectó sola. |
siigo_get_config | Muestra la configuración (claves enmascaradas). |
siigo_read_xlsx | Lee de forma paginada cualquier .xlsx generado. |
En el perfil core, una sola: siigo_run_function, que ejecuta cualquiera de las 47 por
nombre. En all, una por función con el nombre en minúsculas (siigo_getmov, siigo_getter,
siigo_pushmov...). Las dos rutas construyen exactamente el mismo argv, y hay un test que lo
compara lado a lado.
Todas aceptan los mismos campos comunes — empresa (obligatorio), anio, norma,
instalacion, usuario, clave — más los parámetros propios de la función. Las de
exportación admiten además filasPreview.
siigo_run_function exige confirmarEscritura: true para las funciones PUSH*. Al colapsar
47 herramientas en una se pierde el destructiveHint por función, y una importación escribe en la
contabilidad sin que el servidor pueda deshacerla; la protección pasa a ser explícita.
siigo://guia/inicio trae la misma guía que --help, y siigo://funcion/{nombre} la firma de
una función en markdown, para consultarla sin gastar una llamada de herramienta. El prompt
siigo_puesta_en_marcha recorre el arranque completo. Los recursos no cuestan contexto salvo que
el cliente los pida.
Las funciones GET* devuelven la ruta del .xlsx, el total de filas, las columnas y las
primeras 50 filas ya parseadas, con un siguienteOffset para continuar con siigo_read_xlsx.
Los modelos de SIIGO no empiezan por los títulos: llevan el nombre de la empresa en la fila 1,
el del modelo en la 2, dos filas vacías, y los encabezados en la 5. El lector detecta esa fila
automáticamente y recorta el relleno de espacios que arrastra COBOL. Si algún modelo despista a
la heurística, siigo_read_xlsx acepta filaEncabezado para forzarla.
Se guarda en %APPDATA%\siigo-pyme-mcp\config.json (se puede reubicar con
SIIGO_MCP_CONFIG_DIR).
Precedencia, la misma para las credenciales y para el año: valor de la llamada → variable de entorno → valor de la empresa → valor por defecto (o el año actual).
Consecuencia que conviene tener presente: si define SIIGO_ANO en el entorno del cliente MCP, ese
año manda sobre el campo year de cualquier empresa. Para que una empresa trabaje en otro año,
pase anio en la llamada, o quite SIIGO_ANO del entorno y deje solo los year por empresa.
siigo_doctor avisa cuando detecta esa situación, porque consultar el año contable equivocado no
se nota en la respuesta.
Hasta la 0.2.0 el año de la empresa ganaba a
SIIGO_ANO, al contrario que las credenciales. Si usaba las dos fuentes a la vez, revise qué año va a consultar antes de actualizar a 0.3.0.
outputDir debe ser corto: SIIGO limita la ruta del .xlsx a 50 caracteres. siigo_doctor
calcula el margen que queda y avisa antes de que el CLI empiece a truncar en silencio.
| Variable | Para qué |
|---|---|
SIIGO_USUARIO, SIIGO_CLAVE | Credenciales, como alternativa a guardarlas en el config.json. |
SIIGO_ANO | Año de proceso por defecto, 4 dígitos. |
SIIGO_TOOLS | core (por defecto) o all. Ver Herramientas. |
SIIGO_MCP_CONFIG_DIR | Reubica la carpeta de configuración. |
Diez comprobaciones, todas se ejecutan siempre: plataforma, Node, instalaciones de SIIGO, Excel,
sesión de escritorio, configuración, credenciales, empresas accesibles, carpeta de salida y
procesos de SIIGO o Excel vivos. Cada resultado que no esté en [ ok ] viene con una acción
concreta, y la última línea es siempre el paso que desbloquea.
Nunca ejecuta EXCELSIIGO.exe, no lanza Excel y no escribe ningún archivo. Detecta Excel por el
registro (App Paths, y el ProgID COM como respaldo) y la sesión por el número de sesión del
propio proceso: instanciar Excel para comprobar que existe se colgaría en una máquina sin
escritorio, que es justo el fallo que hay que diagnosticar. La clave nunca aparece en el informe;
hay un test que serializa el informe completo y falla si la encuentra.
La misma información está disponible como herramienta MCP, siigo_doctor, una vez registrado.
Nacen del ejecutable de SIIGO, no del servidor:
EXCELSIIGO.exe la recibe como argumento
posicional, así que aparece en Get-CimInstance Win32_Process mientras dura la ejecución.
No hay forma de evitarlo desde fuera. El servidor sí la mantiene fuera de logs, mensajes de
error y respuestas MCP.GETTER de mil terceros ronda el minuto; un GETMOV de un
año completo con 25 000 movimientos, algo más de dos. El servidor emite notificaciones de
progreso para que el cliente no aborte la llamada por silencio, y corta a los 180 segundos
por defecto (timeoutMs en la configuración).020 o 105. El servidor lo
distingue de un error corriente y devuelve moduloNoDisponible: true: reintentar no cambia
nada, hay que habilitar el módulo en SIIGO o usar otra función..xlsx de salida y al log. El servidor genera
nombres cortos y avisa antes de invocar si una ruta se pasa.exit code 0 no significa éxito. El binario puede fallar (081 Parámetros de la función tienen errores) y salir con 0. El servidor combina tres señales antes de dar por buena una
corrida: código de salida, contenido del log y existencia y tamaño del archivo generado.TEMP de la empresa, según documenta
el manual, no en la ruta que se indique.test:e2e es el único script que necesita SIIGO instalado; el resto corre en cualquier
máquina, incluida la de CI.
Sin credenciales corre la prueba negativa: usa unas inválidas a propósito y exige que el
servidor reporte el fallo, que es justo lo que el binario no hace por su cuenta. Con
credenciales válidas corre la prueba positiva, que ejecuta un GETTER real y verifica que
el .xlsx exista, pese más de cero y traiga columnas y filas legibles:
test:tools recorre las herramientas del perfil all: invoca las de apoyo, ejecuta de verdad las 29
exportaciones contra la empresa, y prueba las 18 importaciones solo por su ruta de
validación. Las importaciones escriben en la contabilidad y ese script no puede deshacerlo,
así que comprueba el esquema, la resolución de empresa y credenciales y la construcción del
argv, y verifica que rechacen un archivo de entrada inexistente antes de lanzar el ejecutable.
Su argv sí está cubierto al completo por los tests dorados. Para probar una importación de
verdad, use una empresa de pruebas.
El manual de SIIGO (<instalación>\ExcelSIIGO-Ayuda.LOG) trae una línea Ejemplo: por cada
función. src/siigo/args.golden.test.ts reconstruye el argv con esos mismos valores y exige
que coincida token por token. Es la única defensa real contra el error 081, que el binario
reporta en silencio. Si corrige la firma de una función en src/catalog/functions.ts, el test
correspondiente se lo confirmará.
La publicación es automática. No se publica nada a mano.
ci.yml valida cada PR y cada push a main en un runner de Windows: typecheck, tests,
build, smoke y comprobación de que el tarball solo lleva artefactos de distribución.publish.yml se dispara al empujar un tag v* y, tras repetir la validación completa,
publica a npm con --provenance, publica al MCP Registry oficial autenticando con el OIDC
de GitHub Actions, y crea la GitHub Release con notas generadas.Para sacar una versión:
El workflow bloquea la publicación si package.json, el tag y server.json no coinciden:
el MCP Registry rechaza con 422 cuando las versiones difieren, y es mejor fallar antes de
haber subido nada a npm.
Configuración necesaria una sola vez en el repositorio: el secret NPM_TOKEN con un token
de tipo Automation de npm (los tokens Automation omiten el 2FA, que un runner no puede
resolver). El MCP Registry no necesita ningún secret.
MIT. Proyecto independiente, sin relación con Informática y Gestión S.A. (SIIGO).