BeeL.

Facturación electrónica española con VeriFactu (AEAT): emite facturas, gestiona clientes, valida NIFs.

Documentación

Servidor MCP BeeL — Facturación electrónica VeriFactu para agentes de IA

Servidor MCP de facturación electrónica española con VeriFactu (AEAT): crea, emite y rectifica facturas desde Claude, ChatGPT, Cursor o VS Code.
Servidor MCP para facturación electrónica española con cumplimiento VeriFactu: emite, corrige y registra facturas con la AEAT directamente desde tu agente de IA.
beel.es · Documentación de la API · Guía MCP · npm

Un servidor MCP (Model Context Protocol) que permite a un agente de IA emitir facturas electrónicas españolas legalmente conformes — registro VeriFactu con la AEAT, tipos de factura F1/F2, correctivas 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 escribas ni una sola llamada a la API.

No es un envoltorio generado alrededor de una API. Tres cosas lo hacen utilizable por un modelo:

Las herramientas derivan del contrato OpenAPI público, por lo que el esquema de entrada de cada herramienta es el esquema real de la operación: enums, 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, el cableado de webhooks y las operaciones obsoletas se excluyen por regla, no a mano.
Las salvaguardas fiscales viajan con las herramientas: los invariantes que un envoltorio generado pasaría por alto, 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.

Un solo código base, dos transportes: el servidor remoto alojado en https://mcp.beel.es/mcp (Streamable HTTP + OAuth — un inicio de sesión por usuario, nada que instalar), y un servidor local stdio construido desde este repositorio para uso sin interfaz, donde una clave de API 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. Nada que instalar y ninguna clave de API que gestionar: el servidor actúa con tus propias credenciales, y el flujo OAuth se descubre desde la URL.

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

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

Ejecutarlo localmente

Usa el servidor local cuando OAuth no pueda: un trabajo programado que emite facturas, un pipeline de CI, o cualquier proceso sin interfaz donde no haya nadie presente para completar un inicio de sesión en el navegador. Se autentica con una clave de API en su lugar.

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 prefijo beel_sk_test_ son seguras para experimentar; beel_sk_live_ emite documentos fiscales reales.

Las versiones se publican desde CI mediante publicación confiable de npm, por lo que llevan procedencia: npm registra la confirmación y el flujo de trabajo exactos de los que proviene cada compilación. Verifícalo con npm audit signatures.

Cada versión también se anuncia al Registro MCP como es.beel/mcp, listando ambos transportes, para que los clientes que navegan por el registro encuentren el servidor sin que se les indique dónde está. El nombre está autenticado por un registro DNS en beel.es, por lo que indica que el servidor proviene de nosotros y no meramente de algún repositorio.

Una lista anterior bajo io.github.beel-es/beel-mcp (v0.2.2) se retiró cuando el nombre se movió. Los nombres del registro son identidades más que etiquetas, por lo que un cambio de nombre es una nueva entrada más que una redirección; ambos apuntan al mismo paquete npm y al mismo servidor alojado.

Qué proporciona

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 la documentación, y beel_get_setup_status, que informa por NIF exactamente qué falta antes de poder emitir y la siguiente acción única a tomar.
Recursos de salvaguarda bajo beel://guardrails/* — los invariantes fiscales, más beel://guardrails/errors, un catálogo de cada código de error con la acción que requiere. Sus resúmenes se integran en la descripción de cada herramienta que restringen.
7 indicaciones de flujo de trabajo que codifican el orden seguro de operaciones para los flujos donde el orden es lo que los hace seguros: issue-invoice (validar NIF → elegir F1/F2 → comprobar las puertas VeriFactu → emitir), fix-invoice (anular vs corregir), onboard-nif, setup-representation, invite-member, connect-payments y upgrade-integration.
Visor de PDF de facturas integrado (MCP Apps): generar un PDF de factura lo abre en un panel lateral en los hosts que lo admiten.

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

Qué no es deliberadamente una herramienta

Descargas binarias (vista previa de PDF, ZIP masivo, exportación Excel/CSV), subidas multipart (importación CSV/Holded, envío de PDF firmado), infraestructura de webhooks, y cada operación deprecated. Un agente no puede manejarlas, y cada una cuesta 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 errará solo con el esquema — anular una factura que debería haberse corregido, usar R1 en una factura simplificada, editar una que la AEAT ya ha registrado. El servidor lo aborda en tres capas, y la diferencia entre ellas importa:

1. Consultiva — src/guardrails/rules/*.md, un archivo Markdown por tema: el ciclo de vida de la factura, anular vs rectificar, tipos de factura, líneas de factura, claves de régimen, numeración de series, validación de NIF, las puertas VeriFactu, cuentas multi-NIF. Cada uno se expone como un recurso MCP bajo beel://guardrails/* y su resumen de una línea se añade a la descripción de cada herramienta que restringe, para que la restricción viaje con la llamada.

2. Aplicada — src/guardrails/validate.ts, comprobada antes de enviar la solicitud, por lo que una carga útil incorrecta nunca consume ni siquiera una clave de idempotencia:

Comprobación	Código
Exactamente un campo de precio por línea	`LINE_UNIT_PRICE_XOR_DECLARED_TOTAL`
Sin descuento sobre un total declarado	`LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT`
Sin retención de IRPF en una factura simplificada (F2)	`SIMPLIFICADA_FORBIDS_IRPF`
Recargo de equivalencia solo bajo el régimen `18`, y `18` solo con uno	`SURCHARGE_REQUIRES_REGIME` / `REGIME_REQUIRES_SURCHARGE`
El formato de serie puede distinguir sus períodos de reinicio	`SERIES_ANNUAL_REQUIRES_YEAR` / `SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR`
La numeración solo se siembra en la llamada que activa la empresa	`NUMBERING_REQUIRES_ACTIVATION`
Las líneas `SUPLIDO` llevan su referencia de origen	comprobado localmente
Texto de exención solo bajo el motivo `OTRO`	comprobado localmente
Las correctivas pasan por su propia operación, no por `type: CORRECTIVE`	comprobado localmente

3. Explicada — la API de BeeL ya responde bien: su message está escrita para un humano en el idioma del llamante, error.details lleva los detalles específicos, y el campo type RFC 7807 enlaza a una página de documentación para ese código exacto (alrededor de 357 de ellos). El servidor retransmite todo eso sin cambios, y añade solo las dos cosas que una respuesta no puede llevar: el remedio como llamada a herramienta — la documentación se dirige a alguien con el panel abierto ("crea una serie en ajustes"), un agente necesita beel_set_default_series — y si reintentar puede ayudar en absoluto, que es lo que detiene a un agente en bucle sobre un 403 que necesita un administrador. src/guardrails/catalog.ts contiene solo códigos donde una de esas cosas aplica; todo lo demás pasa, porque una paráfrasis sería peor que el original y se desviaría de él. El blockers[] anidado de EMISSION_NOT_READY son el caso más claro: llegan como cadenas simples sin mensaje ni enlace, y cada uno sale de nuevo nombrando la herramienta que lo resuelve.

La API de BeeL es la autoridad en todo ello. Cada regla aplicada refleja un rechazo que el contrato documenta, por lo que la comprobación previa es un subconjunto estricto de lo que la API rechaza: solo puede hacer el fallo más rápido y mejor explicado, nunca permitir algo que la API rechazaría. Las reglas que dependen del estado del lado del servidor — coincidencia del censo AEAT, el techo de 3 000 € para F2, si una serie existe — permanecen consultivas a propósito, porque adivinarlas localmente rechazaría facturas válidas. Establece BEEL_DISABLE_PREFLIGHT=1 para omitir las comprobaciones locales por completo.

Las listas curadas a mano están ancladas por pruebas: cada código catalogado debe seguir apareciendo en el contrato, cada operationId comprobado debe seguir resolviendo a una herramienta real, y cada referencia de salvaguarda debe apuntar a una salvaguarda que exista. Un cambio de nombre en la API falla en CI en lugar de desactivar silenciosamente una comprobación fiscal.

Configuración

Solo servidor local

Variable	Propósito
`BEEL_API_KEY`	Clave de API. El prefijo selecciona el entorno: `beel_sk_test_` → Pruebas, `beel_sk_live_` → Producción.
`BEEL_ENV` / `BEEL_CONFIG_DIR`	Opcional. Con `BEEL_API_KEY` sin establecer, recurre al `~/.config/beel/config.json` de la CLI (`beel login`); `BEEL_ENV` (`test`/`live`, predeterminado `test`) elige qué clave almacenada.

Compartida

Variable	Propósito
`BEEL_BASE_URL`	URL base de la API. Predeterminado `https://app.beel.es/api`.
`BEEL_DOCS_URL`	Fuente de documentación para las herramientas de documentación. Predeterminado `https://docs.beel.es`.
`BEEL_REQUEST_TIMEOUT_MS`	Límite máximo para una sola llamada a la API. Predeterminado `30000`.
`BEEL_DISABLE_PREFLIGHT`	Establecer a `1` para omitir las salvaguardas aplicadas.

Cada valor predeterminado vive en src/shared/defaults.ts; nada está codificado dos veces. Las variables de despliegue remoto están documentadas en DEPLOY.md.

El servidor se inicia y lista herramientas sin credenciales en absoluto — solo da error cuando una herramienta de API se llama realmente. Las solicitudes POST llevan un Idempotency-Key estable derivado de la solicitud misma, por lo que un agente que reintenta "crear factura" nunca puede acuñar una segunda factura.

Autoalojamiento

El servidor remoto se ejecuta en Cloudflare Workers. Consulta DEPLOY.md para el espacio de nombres KV, el cliente OAuth que BeeL debe haber 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, recuento de operaciones y hash. CI falla si los dos no coinciden, que es lo que mantiene honesto un contrato incluido. Consulta CONTRIBUTING.md.

El resto del ecosistema de desarrolladores de BeeL

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


API REST	El contrato mismo. Todo lo demás es una proyección de él
CLI	La misma superficie desde una terminal, sandbox por defecto
Nodo n8n	Facturación dentro de un flujo de trabajo sin código
Plugin de Claude Code	Implementa, audita y mantiene una integración de BeeL
Documentación legible por máquina	`llms.txt` para agentes que prefieren leer a adivinar

Preguntas frecuentes

¿Qué es el servidor MCP de BeeL? Un servidor MCP que expone la facturación electrónica española VeriFactu como herramientas que un agente de IA puede invocar — para que Claude, ChatGPT, Cursor o VS Code puedan crear clientes, emitir facturas F1/F2, registrarlas en la AEAT y publicar correctivos 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 necesitas pegar ninguna clave API para uso interactivo.

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

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

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

Contribuciones

Los informes de errores y las solicitudes de extracción son bienvenidos — consulta CONTRIBUTING.md para conocer la estructura del proyecto y qué convenciones son esenciales. Los problemas de seguridad deben enviarse a security@beel.es en lugar de un problema público; consulta SECURITY.md.

Licencia

MIT © BeeL.

_{beel.es · Documentación · Guía del MCP}