BeeL MCP server

Un servidor MCP (Model Context Protocol) que permite a un agente de IA emitir facturas electrónicas españolas con pleno cumplimiento legal — registro VeriFactu ante AEAT, tipos de factura F1/F2, rectificativas R1–R5, validación de NIF contra el censo y las claves de régimen que exige la normativa. Conéctalo a Claude, ChatGPT, Cursor o VS Code y tu agente podrá gestionar la facturación española — facturación electrónica y factura electrónica VeriFactu — de principio a fin, sin que tengas que escribir ni una sola llamada a la API.

No es un envoltorio generado alrededor de una API. Tres cosas hacen que sea útil para un modelo:

• Las herramientas se derivan del contrato público OpenAPI, de modo que el esquema de entrada de cada herramienta es el esquema real de la operación — enumerados, líneas de detalle, claves de régimen y todo lo demás. La superficie no puede desviarse de la API.

• Una política de inclusión de herramientas decide qué se le debe dar realmente a un agente. Las descargas binarias, las subidas multipart, toda la infraestructura de webhooks y las operaciones obsoletas se excluyen por regla, no a mano.

• Las salvaguardas fiscales viajan con las herramientas: las invariantes que un wrapper generado no detectaría, tanto como documentación que el modelo lee como comprobaciones previas que detienen una solicitud no conforme antes de que se convierta en un documento fiscal.

Una única base de código, dos transportes: el servidor remoto alojado en https://mcp.beel.es/mcp (Streamable HTTP + OAuth — un único inicio de sesión por usuario, nada que instalar), y un servidor local stdio construido desde este repositorio para uso sin interfaz gráfica, donde una API key funciona y un inicio de sesión basado en navegador no.

Inicio rápido

Añade https://mcp.beel.es/mcp como conector en Claude, ChatGPT, Cursor o VS Code e inicia sesión con tu cuenta de BeeL. No hay nada que instalar ni ninguna API key que gestionar: el servidor actúa con tus propias credenciales, y el flujo OAuth se descubre automáticamente desde la URL.

# Claude Code
claude mcp add --transport http beel https://mcp.beel.es/mcp

Eso es toda la configuración para uso interactivo. Sigue leyendo solo si necesitas el servidor local.

Related MCP server: chile-invoice-mcp

Ejecutar en local

Usa el servidor local cuando no se pueda usar OAuth: un trabajo programado que emite facturas, un pipeline de CI, o cualquier proceso headless en el que no haya nadie presente para completar un inicio de sesión por navegador. En su lugar, se autentica con una API key.

Requiere Node ≥ 20.

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "beel": {
      "command": "npx",
      "args": ["-y", "@beel_es/mcp"],
      "env": { "BEEL_API_KEY": "beel_sk_test_xxx" }
    }
  }
}

# Claude Code
claude mcp add beel --env BEEL_API_KEY=beel_sk_test_xxx -- npx -y @beel_es/mcp

Las claves con el prefijo beel_sk_test_ son seguras para experimentar; las beel_sk_live_ emiten documentos fiscales reales.

Las releases se publican desde CI mediante la publicación de confianza de npm, por lo que llevan procedencia: npm registra el commit exacto y el workflow del que salió cada build. Verifícalo con npm audit signatures.

Cada release también se anuncia en el Registro MCP como es.beel/mcp, enumerando ambos transportes, de modo que los clientes que exploran el registro encuentren el servidor sin apuntárselo directamente. El nombre está autenticado mediante un registro DNS en beel.es, de modo que indica que el servidor viene de nosotros y no solo de un repositorio.

Un listado anterior con el nombre io.github.beel-es/beel-mcp (v0.2.2) se retiró cuando el nombre se trasladó. Los nombres del registro son identidades, no etiquetas, así que un renombrado es una entrada nueva en lugar de una redirección; ambas apuntan al mismo paquete npm y al mismo servidor alojado.

Qué ofrece

• 118 herramientas de API derivadas de openapi/public-api.yaml — facturas, clientes, productos, facturas recurrentes, series y configuración fiscal, validación de NIF, empresas.

• 4 herramientas sintéticas para las que la API no tiene un endpoint único: beel_docs_search, beel_docs_get, beel_docs_list sobre documentación, y beel_get_setup_status, que informa por NIF exactamente qué falta antes de poder emitir y propone la única acción siguiente.

• Recursos de salvaguarda en beel://guardrails/* — las invariantes fiscales, además de beel://guardrails/errors, un catálogo de todos los códigos de error con la acción que requieren. Sus resúmenes aparecen en la descripción de todas las herramientas a las que constharmonizan.

• 7 workflows o prompts que codifican el orden seguro de operaciones para los flujos en los que el orden es lo que los hace seguros: issue-invoice (validar el NIF → elegir F1/F2 → comprobar las puertas de VeriFactu → emitir), fix-invoice (contrarrango vs. corregir), onboard-nif, setup-represent, invite-member, connect-payments y upgrade-integration.

• Visor inline de PDF de facturas (MCP Apps: generar un PDF de factura lo abre en un panel lateral en los hosts que lo soportan.

Un catálogo generado de todas las herramientas, con los ámbitos que requiere cada una, está en docs.beel.es/mcp/tools (npm run tools:catalog).

Lo que no es deliberadamente una herramienta

Las descargas binarias (vista previa del PDF, ZIP agrupado, exportación Excel/CSV), las subidas multiparte (importación CSV/Holded, envío del PDF firmado), la infraestructura de webhooks y todas las operaciones deprecated. Un agente no puede manejarlos, y cada uno consume un contexto que una herramienta utilizable necesita. Las reglas están en src/policy/tool-policy.ts.

Las salvaguardas fiscales

La facturación electrónica española tiene invariantes que un LLM puede fallar solo a partir del esquema — anular una factura que hay que corregir, usar R1 en una factura simplificada, editar una factura ya registrada en AEAT. El servidor las aborda en tres capas, y la diferencia importa:

1. Asesoramiento — src/guardrails/rules/*.md, un archivo Markdown por tema: ciclo de vida de facturas, anular vs. corregires, tipos de factura, líneas de factura, claves de ejemplo, numeración de series, validación de NIF, puertas de VeriFactu, cuentas multi-NIF. Cada tema se expone como un recurso MCP bajo beel://guardrails/* ín y su resumen de una línea se adjunta a la descripción de cada herramienta asociada, de modo que la restricción acompaña a la llamada.

2. Obligatoriedad — src/guardrails/validate.ts, que se comprueba antes de enviar la solicitud, para que una carga no válida nunca consuma una clave de idempotencia:

3. Explicación — La API de BeeL ya responde de forma correcta: su message está escrito por una persona para el idioma de quien llama, error.details contiene los detalles concretos, y el campo type de RFC 7807 enlaza con una página de documentación sobre ese código concreto (unos 357). El servidor lo transmite todo sin cambios, y solo añade las dos cosas que una respuesta no puede llevar: la solución como emisión de la herramienta — la documentación se dirige a alguien con el panel de control abierto (“crear una serie en settings”), un agente lo dirige a beel_set_default_series — y si reintentar puede ayudar o no, que es lo que evita que un agente se quede bucleado en un 403 que requiere un administrador. src/guardrails/catalog.ts contiene solo los códigos en los que se aplica alguna de esas acciones; el resto se deja pasar, porque una paráfrasis sería peor que el original y se desviaría de él. El anidado blockers[] de EMISSION_NOT_READY es el caso más claro: llegan como cadenas desnudas sin mensaje ni enlace, y cada una sale indicando la herramienta que lo limpia.

La API de BeeL es la autoridad en todo lo anterior. Cada regla que se aplica refleja un rechazo documentado en el contrato, por lo que la pre-verificación es un subconjunto estricto de lo que la API rechaza: solo puede hacer que el fallo sea más rápido y esté mejor explicado, nunca permitir algo que la API rechazaría. Las reglas que dependen del estado servidor —comparar el censo de AEAT, el límite F2 de 3.000 €, si existe una serie— se quedan deliberadamente en asesoramiento porque adivinarlas rechazaría facturas válidas. Para omitir por completo las comprobaciones locales, establece BEEL_DISABLE_PREFLIGHT=1.

Las listas seleccionadas a mano se anclan con pruebas: cada código del catálogo debe seguir apareciendo en el contrato, cada operation verificada debe resolver una herramienta real, y cada link de una salvaguarda debe apuntar a un guide real. Una API que cambia de nombre falla en la CI, en lugar de apagar silenciosamente una comprobación fiscal.

Configuración

Solo para el servidor local

Shared

Todos los valores por defecto viven en src/shared/defaults.ts; nada está codificado dos veces. Las variables para el despliegue remoto se documentan en DEPLOY.md.

El servidor se inicia y lista las herramientas sin ninguna credencial; solo se produce un error cuando se llama realmente a una herramienta de API. Las solicitudes POST llevan una Idempotency-Key estable derivada de la propia solicitud, por lo que un agente que reintente “crear factura” nunca podrá emitir una segunda factura.

Autoalojamiento

El servidor remoto se ejecuta en Cloudflare Workers. Consulta DEPLOY.md para conocer el espacio de nombres KV, el cliente OAuth que BeeL debe tener registrado y los secretos involucrados.

Desarrollo

npm ci
npm run dev          # stdio server from source
npm test             # vitest
npm run typecheck    # both the Node and the Worker configs
npm run build        # single-file bundle to dist/index.js
npm run inspect      # MCP Inspector against the local build
npm run spec:verify  # the vendored contract still matches its lock

openapi/public-api.yaml es una copia generada del contrato de la API, y openapi/spec.lock.json registra su versión, número de operaciones y hash. La CI falla si ambos no coinciden, lo que garantiza que el contrato integrado sea veraz. Consulta CONTRIBUTING.md.

El resto del ecosistema de desarrollo de BeeL

Todo lo que sigue deriva del mismo contrato OpenAPI, por lo que el vocabulario — tipos de factura, claves de régimen, series, estados VeriFactu — es idéntico allí donde lo encuentres.

Preguntas frecuentes

¿Qué es el servidor MCP de BeeL? Un servidor MCP que expone la facturación electrónica VeriFactu de España como herramientas que un agente de IA puede invocar, de modo que Claude, ChatGPT, Cursor o VS Code puedan crear clientes, emitir facturas F1/F2, registrarlas en la AEAT y presentar correctivas R1–R5 en tu nombre.

¿Cómo conecto la facturación VeriFactu a Claude / ChatGPT / Cursor? Añade https://mcp.beel.es/mcp como conector e inicia sesión con tu cuenta de BeeL; consulta Inicio rápido. No hay nada que instalar y no tienes que pegar ninguna clave API para el uso interactivo.

¿Es realmente compatible con VeriFactu? Sí. Las facturas se registran en la AEAT conforme a VeriFactu, la numeración y las series siguen la normativa, y las salvaguardias fiscales detienen las solicitudes no conformes antes de que se conviertan en un documento fiscal.

¿VeriFactu o TicketBAI? Este servidor está orientado a VeriFactu, el sistema nacional de la AEAT. El régimen de TicketBAI (el del País Vasco) queda fuera de alcance.

¿Puedo usarlo sin un agente de IA? Sí: es un servidor MCP estándar, así que cualquier cliente con capacidad MCP funciona, y la misma superficie de facturación está disponible como REST API, CLI y n8n node.

Contribuciones

Los informes de errores y los pull requests son bienvenidos — consulta CONTRIBUTING.md para ver cómo está organizado el proyecto y qué convenciones son imprescindibles. Los problemas de seguridad se reportan a security@beel.es en lugar de una incidencia pública; consulta SECURITY.md.

Licencia

MIT © BeeL.