informer-mcp

Un servidor Model Context Protocol para la API de contabilidad Informer (v2). Ofrece a cualquier cliente MCP acceso directo a tus relaciones, facturas de venta y compra, presupuestos, pedidos, recibos, productos e informes financieros.

Cada herramienta se deriva del documento OpenAPI propio de Informer (api.informer.eu/docs/v2). El servidor incluye una copia para que funcione sin conexión, y se mantiene al día; consulta Mantenerse al día con los cambios de la API.

Proyecto no oficial. Sin afiliación ni respaldo de Informer.

Inicio rápido

Pega esto en cualquier asistente de IA que pueda instalar servidores MCP:

Install the following MCP server: https://github.com/vladxyz/informer-mcp and run the local setup screen for the API keys.

Clonará el repositorio, lo compilará, registrará el servidor en tu cliente y luego ejecutará informer-mcp setup, que abre una página en tu navegador en 127.0.0.1. Esa página es donde van tus credenciales de API; no se pide nada en el chat y ninguna clave se pega nunca en una conversación.

Qué ves en esa página

Una tarjeta por administración, más Añadir administración si gestionas más de una:

┌─ Administration ────────────────────────────── Remove ─┐
│  ALIAS                        COMPANY NAME             │
│  [ acme                ]      [ ACME BV           ]    │
│  Short handle you use         Optional, shown in       │
│  in prompts.                  tool descriptions.       │
│                                                        │
│  API KEY                      SECURITY CODE            │
│  [ •••••••••••••••••  ]      [ •••••••••••••••  ]     │
│                                                        │
│  ACCESS                                                │
│  [ Read and write   ▾ ]                                │
│  Read only hides every tool that changes this          │
│  client's books.                                       │
└────────────────────────────────────────────────────────┘

  [ Add administration ]   [ Verify & save ]   ☐ Save without verifying

Ambas credenciales pertenecen a una administración, así que un contable añade una tarjeta por cliente. Consulta Varias administraciones de clientes.

Qué ocurre al pulsar Verificar y guardar

1. Cada par clave/código de seguridad se prueba contra la API, y la página te muestra el nombre de la empresa al que pertenece realmente; así, una clave pegada en la fila equivocada es evidente antes de que se guarde nada.

2. Si un par es rechazado, no se escribe nada y se nombra la fila que falla. Marca Guardar sin verificar para guardarlo de todos modos, por ejemplo cuando estés sin conexión.

3. Si tiene éxito, las credenciales se escriben en ~/.informer-mcp.json con permisos 0600. Si se abrió mediante open_setup, el servidor en ejecución recoge el cambio de inmediato: una nueva administración es seleccionable en el siguiente mensaje. Si se abrió desde una terminal, reinicia tu cliente.

Pregunta "¿a qué administraciones tienes acceso?" para confirmarlo: eso llama a list_administrations y enumera cada alias con su empresa.

Related MCP server: billingo-mcp

Qué obtienes

• 68 herramientas que cubren los 49 endpoints documentados — lectura y escritura.

• Configuración en el navegador. Pide a tu asistente que abra la página de configuración, o ejecuta informer-mcp setup. Comprueba cada clave contra la API, escribe el archivo de configuración y el cambio surte efecto sin reiniciar nada.

• Sigue la API. Cuando Informer publica un nuevo endpoint, el servidor lo detecta y añade la herramienta mientras tu cliente sigue conectado: sin reinstalar, sin reiniciar.

• Varias administraciones de clientes en un solo servidor. Los contables pueden acceder a los libros de cada cliente desde una única conexión, con un argumento administration que es obligatorio siempre que haya más de una configurada.

• Una pregunta para toda la cartera. Las herramientas de solo lectura aceptan una lista de alias o "all" y las consultan de forma concurrente, devolviendo resultados indexados por cliente.

• Esquemas de solicitud completos. Las herramientas de crear/actualizar anuncian el JSON Schema completo de su payload, para que el modelo sepa qué campos existen y cuáles son obligatorios antes de enviar nada.

• Solo lectura o lectura-escritura, a tu elección. Una opción --read-only oculta toda herramienta que cambie algo, y clientes individuales pueden fijarse como solo lectura mientras el resto sigue siendo escribible. Las listas de permitidos/denegados reducen aún más la superficie.

• PDFs y adjuntos se decodifican desde base64 y pueden escribirse directamente en disco.

• HTTP resiliente. Timeouts, reintentos con soporte de Retry-After, y los errores de validación en neerlandés de Informer se muestran tal cual (HTTP 422: invoice_date: ongeldig).

Requisitos

• Node.js 20 o superior

• Una cuenta de InformerOnline con acceso a la API

Configuración de tus credenciales

Basta con pedirlo en la conversación:

"Quiero cambiar mis administraciones de Informer" "Añadir un nuevo cliente a Informer" "Mi clave de API de Informer ha cambiado"

Tu asistente llama a la herramienta open_setup y la página se abre. No hay ningún archivo de configuración que buscar ni nada que editar a mano; y como la página es un formulario de navegador, tu clave de API nunca tiene que escribirse en un chat.

La misma página desde una terminal:

npm run setup          # or: informer-mcp setup

De cualquier manera, obtienes http://127.0.0.1:<port> en tu navegador, con un formulario para cada administración: alias, nombre de la empresa, clave de API, código de seguridad, y si se puede escribir en ella. Al guardar se verifica cada par contra la API — así una clave mal escrita se detecta de inmediato, y ves el nombre de la empresa al que pertenece realmente cada clave — y después escribe ~/.informer-mcp.json con permisos 0600.

Iniciar el servidor sin credenciales abre automáticamente la misma página, ya que es exactamente el momento en que la necesitas. Establece INFORMER_AUTO_SETUP=false para desactivarlo, o INFORMER_OPEN_BROWSER=false en una máquina sin interfaz gráfica para que solo imprima la URL. Sin importar cómo se haya abierto, solo hay una página: si la pides de nuevo, se te devuelve la misma URL.

Algunas cosas que la página hace deliberadamente:

• se vincula solo a 127.0.0.1, y cada ejecución genera un token aleatorio que debe estar en la URL y en la solicitud de guardado, para que otro sitio en tu navegador no pueda enviar datos a la página;

• nunca envía las claves almacenadas de vuelta a la página: las administraciones existentes aparecen con sus credenciales en blanco y se conservan a menos que escribas un valor nuevo;

• se niega a guardar credenciales que la API rechaza, a menos que marques Guardar sin verificar.

Nada te impide escribir el archivo o las variables de entorno a mano; la página es una comodidad, no un requisito.

De dónde salen las claves

La API se autentica con dos cabeceras, ambas obligatorias:

Ambas están limitadas a una administración: la clave de API pertenece a la administración en la que se creó (GET /administration devuelve "la administración vinculada a esta clave de API") y el código de seguridad identifica a esa empresa. No existe ningún endpoint que enumere administraciones o cambie entre ellas.

Una clave concede acceso completo a los libros de esa administración. Trátala como una contraseña: mantenla en tu entorno, en un gestor de secretos o en un archivo de configuración fuera del repositorio.

Varias administraciones de clientes

Un contable con varios clientes necesita un par clave/código de seguridad por administración de cliente: un usuario contable con acceso a una administración puede crearlos desde su configuración. Añádelos en la página de configuración, o escribe ~/.informer-mcp.json (o cualquier archivo nombrado por INFORMER_CONFIG_FILE) tú mismo:

{
  "administrations": {
    "acme":     { "label": "ACME BV",         "api_key": "...", "security_code": "..." },
    "bakkerij": { "label": "Bakkerij de Bol", "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

Con más de una administración configurada, toda herramienta requiere un argumento administration, anunciado como una enumeración de tus alias:

list_sales_invoices({ "administration": "acme", "filter": "open" })

Deliberadamente no hay valor por defecto. Contabilizar una factura en el libro mayor del cliente equivocado es el único error que no debe ocurrir en silencio, así que una llamada sin el argumento es rechazada por la validación del esquema antes de que se haga cualquier solicitud HTTP — igual que un alias que nunca configuraste.

list_administrations muestra los alias configurados; pasa verify: true para obtener el nombre de cada empresa desde la API, lo que confirma tanto que las credenciales funcionan como que cada alias apunta a la empresa que crees que es.

Consultar varios clientes a la vez

Las herramientas de solo lectura también aceptan una lista de alias, o "all":

list_sales_invoices({ "administration": "all", "filter": "open", "records": 50 })
list_sales_invoices({ "administration": ["acme", "bakkerij"], "filter": "open" })

Las administraciones se consultan de forma concurrente (INFORMER_FANOUT_CONCURRENCY, cuatro a la vez por defecto) y la respuesta se indexa por alias:

{
  "administrations": ["acme", "bakkerij"],
  "results": {
    "acme": { "pagination": { "total": 3 }, "invoices": [ ... ] },
    "bakkerij": { "error": "[bakkerij] HTTP 401: Authentication failed" }
  }
}

Tres propiedades que conviene conocer:

• Que un cliente falle no hunde la consulta. Su entrada lleva un error y el resto sigue devolviendo datos.

• El presupuesto de respuesta se reparte a partes iguales. Cada administración recibe INFORMER_MAX_RESPONSE_CHARS / n caracteres, para que un cliente grande no desplace a los demás; cualquier exceso sobre su parte se devuelve como { "truncated": true, "partial": ... }.

• El fan-out es de solo lectura. Las herramientas que escriben, y las descargas de PDF/adjuntos, aceptan un único alias: su esquema ni siquiera ofrece el array ni "all", y el manejador las rechaza una segunda vez. Crear la misma factura en doce administraciones nunca es un accidente que merezca la pena habilitar.

Una sola administración sigue devolviendo el payload de la API sin envolver, exactamente igual que antes.

Con una sola administración — el caso habitual — nada cambia: establece INFORMER_API_KEY e INFORMER_SECURITY_CODE como siempre y el argumento sigue siendo opcional.

Instalación

git clone https://github.com/vladxyz/informer-mcp.git
cd informer-mcp
npm install          # also builds dist/ via the prepare script
npm run setup        # opens a local page to enter your API credentials

La página de configuración se ejecuta en 127.0.0.1, verifica cada clave contra la API y escribe ~/.informer-mcp.json. Consulta Configuración de tus credenciales.

Claude Desktop, como extensión

La vía más sencilla: compila un bundle y ábrelo.

npm run bundle          # writes informer-mcp.mcpb

En Claude Desktop ve a Configuración → Extensiones → Configuración avanzada → Instalar extensión… y elige el archivo .mcpb. Lleva sus propias dependencias, así que no hay nada que instalar antes aparte de Node.js 20.

El diálogo de instalación ofrece una clave de API, un código de seguridad y un interruptor de solo lectura. Puedes dejar los tres vacíos: el servidor abrirá entonces su página de configuración la primera vez que se inicie, que es también la única forma de configurar más de una administración.

Configuración → Conectores → Añadir conector personalizado de Claude Desktop es otra cosa: toma la URL de un servidor MCP remoto. Este se ejecuta localmente a través de stdio, así que se instala como extensión y no como conector.

Claude Desktop, manualmente

Edita el archivo de configuración directamente:

{
  "mcpServers": {
    "informer": {
      "command": "node",
      "args": ["C:\\path\\to\\informer-mcp\\dist\\index.js"]
    }
  }
}

Reinicia Claude Desktop después. En Windows, las barras invertidas en JSON deben duplicarse; las barras normales también funcionan y son más fáciles de leer.

Cualquier otro cliente MCP

El servidor habla MCP a través de stdio, así que todos los clientes lo configuran de la misma manera: un comando y sus argumentos. El bloque anterior funciona tal cual en Claude Code (claude mcp add), Cursor, Zed, o cualquier otra cosa que hable MCP.

Las credenciales provienen de ~/.informer-mcp.json, así que no es necesario repetirlas en la configuración del cliente. Para pasarlas por cliente en su lugar, añade un bloque env con INFORMER_API_KEY e INFORMER_SECURITY_CODE, o apunta INFORMER_CONFIG_FILE a otro lugar.

Añade "--read-only" a args para registrar un servidor que no pueda cambiar nada: consulta Solo lectura o lectura y escritura. Registrar el mismo servidor dos veces con dos nombres, uno de solo lectura y otro de lectura y escritura, funciona bien.

stdout lleva el protocolo, así que todo el registro va a stderr: un aviso de una línea al inicio te indica cuántas herramientas se registraron y qué administraciones encontró.

Solo lectura o lectura y escritura

Por defecto, todas las herramientas están disponibles. Para eliminar por completo las herramientas de escritura, inicia el servidor con una opción:

informer-mcp --read-only     # only the tools that read
informer-mcp --read-write    # the default: create, update and delete too

INFORMER_READ_ONLY=true hace lo mismo, y la opción tiene prioridad sobre la variable; así puedes registrar el mismo servidor dos veces en un mismo cliente: una vez de solo lectura para las preguntas cotidianas y otra de lectura y escritura para las sesiones en las que realmente registras algo.

En el modo de solo lectura, las herramientas de escritura no se registran en absoluto: nunca aparecen en la lista de herramientas, por lo que un modelo no tiene nada a lo que recurrir.

Por cada cliente

Las administraciones individuales se pueden fijar en el archivo de configuración, que es lo más útil cuando solo puedes consultar los libros de algunos clientes:

{
  "administrations": {
    "acme":     { "api_key": "...", "security_code": "..." },
    "bakkerij": { "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

"read_only": true funciona como abreviatura. La configuración más restrictiva es la que gana:

Así, un cliente marcado como de solo lectura nunca puede escribirse por accidente, y una sesión iniciada con --read-only se mantiene así sin importar lo que diga el archivo de configuración.

Cuando algunas administraciones son de solo escritura y otras no, las herramientas de escritura se mantienen registradas, pero su enum administration solo ofrece las que son de escritura. Crear una factura en un cliente de solo lectura se deniega antes de realizar cualquier petición HTTP:

Administration(s) bakkerij are configured as read-only, so this tool cannot change them.
Writable: acme, garage.

list_administrations informa del modo efectivo de cada cliente, y el banner de inicio lo resume: read-write: acme, garage.

Configuración

Los filtros aceptan una etiqueta OpenAPI o un nombre de herramienta y se comparan sin distinguir entre mayúsculas, minúsculas ni puntuación:

# read-only access to invoicing data
INFORMER_TOOLS="Sales Invoices,Relations" node dist/index.js --read-only

# everything except deleting attachments
INFORMER_EXCLUDE_TOOLS=delete_sales_invoice_attachment node dist/index.js

Uso

Una vez conectado, pide en lenguaje sencillo:

• "¿Qué facturas de venta de 2026 están todavía sin pagar?" → list_sales_invoices con filter

• "Crea una factura en borrador para ACME por 10 horas de consultoría a 125 €." → get_sales_invoice_options para los identificadores válidos de libro mayor, IVA y plantilla, y luego create_sales_invoice

• "Descarga la factura 12345 como PDF en el escritorio." → get_sales_invoice_pdf con save_path

• "Muestra el balance de situación para el periodo 6 de 2026." → get_balance_report

Convenciones que conviene conocer

• Elige la administración explícitamente. Con varios clientes configurados, todas las herramientas aceptan administración: "<alias>". list_administrations asigna los alias a las empresas, y las herramientas de solo lectura también aceptan una lista o "all".

• Las fechas siempre siguen el formato YYYY-MM-DD.

• Las herramientas de listado están paginadas con page (por defecto 1) y records (por defecto 20), y devuelven un objeto pagination con total y pages.

• Los cuerpos de las peticiones van en un único argumento body. Los parámetros de ruta y de consulta se quedan en el primer nivel, así que update_relation recibe { "id": 42, "body": { ... } }.

• Llama primero a la herramienta *_options para crear documentos. get_sales_invoice_options, get_quotation_options y compañía devuelven los identificadores válidos de libro mayor, IVA, plantilla, moneda y condiciones de pago para tu administración.

• Los informes requieren rangos explícitos. get_balance_report necesita year_from, year_to y period; get_column_balance_report también pide un rango de libro mayor.

PDFs y archivos adjuntos

Informer devuelve los archivos como base64 dentro de JSON. Las herramientas que hacen esto (get_*_pdf, download_sales_invoice_attachment) aceptan un save_path opcional:

• con save_path — el archivo se decodifica y se escribe en esa ruta, y la herramienta devuelve { saved_to, filename, bytes, mime_type };

• sin save_path — el archivo se devuelve como un recurso MCP en línea con el tipo MIME correcto, lo que en documentos grandes puede resultar caro en contexto.

La subida funciona al revés: upload_sales_invoice_attachment toma { filename, file }, donde file es el contenido en base64 (máximo 10 MB; PDF, PNG, JPEG, GIF, DOC(X), XLS(X)).

Referencia de herramientas

npm run tools imprime esta lista a partir de la especificación actual; npm run tools -- --md regenera las tablas siguientes.

Además de las herramientas de endpoint, hay tres que entrega el servidor:

Administración

Relaciones

Contactos

Facturas de venta

Facturas de compra

Facturas recurrentes

Pedidos de venta

Presupuestos

Libro de ventas

Condiciones de pago

Plantillas

IVA

Libros mayores

Centros de coste

Divisas

Diarios

Tipos de suscripción

Adjuntos

Productos

Recibos

Memorándum

Informes

Nomenclatura de herramientas

Los nombres se derivan del método HTTP y de la ruta, no de la prosa, por lo que se mantienen estables entre actualizaciones de la especificación:

Los endpoints que la tabla de nomenclatura no reconoce recurren a <verbo>_<slug de ruta>, de modo que una actualización de la especificación nunca produce una herramienta rota.

Mantenerse al día con los cambios de la API

Las herramientas se generan a partir del documento OpenAPI de Informer, así que cuando Informer añade un endpoint, lo único que falta es una copia actualizada de ese documento. El servidor puede obtenerla por sí mismo.

Tres capas, en orden de precedencia:

1. Una copia descargada, almacenada en caché en ~/.informer-mcp.spec.json.

2. La copia incluida en openapi/api-docs.json, que se distribuye con el servidor y siempre funciona sin conexión.

3. Ninguna de las dos se acepta a ciegas: una descarga debe poder analizarse como un documento OpenAPI 3 con al menos una operación utilizable, o se rechaza y las herramientas actuales se mantienen. Un portal cautivo o una página de mantenimiento no pueden eliminar tu conjunto de herramientas.

De forma programada

Una vez al día, poco después de iniciarse, el servidor comprueba en segundo plano si hay un documento más reciente. El arranque nunca se bloquea y un fallo en la comprobación se registra y se ignora. INFORMER_SPEC_MAX_AGE_HOURS=0 lo desactiva.

Bajo demanda

La herramienta refresh_api_spec hace lo mismo cuando se lo pides, útil cuando falta un endpoint que esperabas o un argumento se rechaza por desconocido:

"Actualiza la descripción de la API de Informer y dime qué ha cambiado."

{
  "adopted": true,
  "api_version": "2.0.0",
  "endpoints": 49,
  "tools": 68,
  "changes": {
    "added":   [{ "tool": "list_projects", "endpoint": "GET /projects" }],
    "removed": [],
    "changed": [{ "tool": "create_sales_invoice", "endpoint": "POST /invoices/sales",
                  "notes": ["body now requires: project_id"] }],
    "unchanged": 66
  },
  "note": "The tool list has been updated; no restart is needed."
}

Pasa dry_run para ver ese informe sin aplicar nada.

El diff es deliberadamente específico: nombra las herramientas que han aparecido y desaparecido, y para las que han cambiado dice qué ha cambiado: un argumento nuevo, uno que ya no existe, un campo que ahora es obligatorio. Esa es la parte que una comparación de rutas a secas pasa por alto, y suele ser la parte que de otro modo aparecería como un desconcertante 422.

Adoptar un documento actualiza el servidor en ejecución: se registran herramientas nuevas, se eliminan las retiradas, se vuelven a anunciar las modificadas y se envía una notificación tools/list_changed para que tu cliente recargue la lista a mitad de sesión.

La copia en el repositorio

npm run update-spec actualiza el documento incluido e informa de qué rutas han entrado y salido. Ese es el comando que debes ejecutar cuando quieras que el cambio quede confirmado para todos los que instalen el servidor; refresh_api_spec solo afecta a tu propia máquina.

Recursos

El servidor también expone el propio documento OpenAPI como recurso MCP en informer://openapi.json, lo que resulta útil cuando quieres que el modelo compruebe una definición de campo sin adivinar.

Desarrollo

npm install         # install + build
npm run setup       # enter credentials in the browser
npm run bundle      # package as informer-mcp.mcpb for one-click install
npm run dev         # run from source with tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run tools       # print the tool surface
npm run update-spec # re-download openapi/api-docs.json and report added/removed paths

Estructura del proyecto

openapi/api-docs.json   vendored OpenAPI 3.0 document — the source of truth
src/openapi.ts          spec → operations: tool names, JSON Schema conversion
src/client.ts           HTTP client: auth headers, retries, error formatting
src/tools.ts            operations → MCP tools, filtering, result formatting
src/server.ts           server assembly (tools + openapi resource)
src/spec.ts             download, validate, cache and diff the OpenAPI document
src/setup.ts            local setup server: verify credentials, write the config file
src/setup-page.ts       the HTML it serves
src/index.ts            stdio entry point and CLI
manifest.json           extension manifest: entry point and install-time settings
scripts/update-spec.mjs refresh the vendored spec
scripts/list-tools.ts   print/regenerate the tool reference
scripts/bundle.mjs      stage production dependencies and pack the .mcpb

Añadir endpoints normalmente no supone ningún cambio de código: el servidor en ejecución los detecta por sí mismo y npm run update-spec confirma el mismo cambio en la copia incluida. Solo las formas de URL realmente nuevas necesitan una regla en la tabla RESOURCES de src/openapi.ts; sin ella, siguen convirtiéndose en herramientas, solo que con un nombre menos descriptivo.

Cómo se convierten los esquemas

OpenAPI 3.0 no es exactamente JSON Schema. De camino a la definición de herramienta MCP:

• Las referencias #/components/schemas/X se convierten en #/$defs/X, con solo el cierre transitivo que cada operación necesita realmente incluido, de modo que las definiciones de herramienta sigan siendo pequeñas;

• nullable: true se convierte en una unión ["type", "null"];

• los parámetros de ruta y consulta se convierten en propiedades de nivel superior, los cuerpos de solicitud van bajo body, y additionalProperties: false evita que los errores tipográficos lleguen a la API.

Los argumentos se validan contra ese esquema antes de realizar cualquier llamada HTTP.

Notas de seguridad

• Este servidor puede crear, actualizar y eliminar registros contables reales. Comience con --read-only si solo necesita informes, fije clientes individuales con "mode": "read-only" y deje que su cliente MCP solicite aprobación para las herramientas de escritura.

• Las credenciales de varios clientes en un mismo proceso significan que una llamada mal enrutada toca los libros de otra persona. El argumento administration obligatorio, la enumeración de alias conocidos, la restricción de solo lectura en la difusión y el prefijo de alias en cada mensaje de error ([acme] HTTP 422: ...) existen por esa razón. Mantenga el archivo de configuración fuera del control de versiones y legible solo por usted.

• Las herramientas están anotadas con readOnlyHint, destructiveHint e idempotentHint, de modo que los clientes que usan esas sugerencias pueden bloquear las riesgosas.

• No se registra nada en stdout y las credenciales nunca se reflejan en la salida de las herramientas ni se envían de vuelta a la página de configuración. open_setup devuelve una URL, nunca una clave: un asistente no tiene forma de leer sus credenciales ni razón para pedírselas en un chat.

• La descripción de la API se descarga sin credenciales, y un documento que no se analiza como un archivo OpenAPI 3 utilizable se rechaza en lugar de adoptarse.

Licencia

MIT — consulte LICENSE.