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 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 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 se 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. Descargas binarias, subidas multipart, infraestructura de webhooks, operaciones que solo una sesión de navegador puede autenticar, y las obsoletas se excluyen por regla, no a mano.
Las salvaguardas fiscales viajan con las herramientas: las 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 señale hacia él. 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

124 herramientas de API derivadas de openapi/public-api.yaml — facturas, clientes, productos, facturas recurrentes, series y configuración fiscal, validación de NIF, empresas.
7 herramientas sintéticas para las que la API no tiene un único endpoint: beel_docs_search, beel_docs_get, beel_docs_list sobre la documentación (el endpoint de búsqueda del sitio de documentación y el Markdown de una página a la vez, o algunas de sus secciones en una sola llamada: una página larga responde con su esquema); beel_rules_list y beel_rules_get sobre el catálogo de reglas fiscales (por id, varios ids a la vez, dominio, palabra clave o código de error); beel_schema_get, los campos de los esquemas de solicitud y respuesta como declaraciones compactas similares a TypeScript del contrato incluido (por nombre de esquema, o por nombre de herramienta para su consulta, cuerpo y tipo de retorno); y beel_get_setup_status, que informa por NIF exactamente qué falta antes de que pueda emitir, la siguiente acción a tomar, y los ids desde los que comienza una integración (empresa, serie predeterminada por tipo de documento, estado de VeriFactu y valores fiscales predeterminados).
Recursos de salvaguarda bajo beel://guardrails/* — las reglas fiscales, un recurso por dominio, las guías de uso de la API, y beel://guardrails/errors, un catálogo de cada código de error con la acción que requiere. Los dominios y guías que aplican se nombran 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 de VeriFactu → emitir), fix-invoice (anular vs corregir), onboard-nif, setup-representation, invite-member, connect-payments y upgrade-integration.
Visor de PDF de facturas en línea (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, operaciones que solo una sesión de navegador puede autenticar, 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 AEAT ya ha registrado. El servidor aborda eso en tres capas, y la diferencia entre ellas importa:

1. Consultivo — dos fuentes, mantenidas separadas a propósito:

Las reglas fiscales son el catálogo que el sitio de documentación publica en docs.beel.es/api/rules.json: cada regla tiene un id (COR-002), un enunciado, por qué existe, su base legal, los códigos de error que la aplican y ejemplos. El servidor lo lee en tiempo de ejecución (en caché, como los otros archivos de documentación) y lo sirve a través de beel_rules_list / beel_rules_get y un recurso por dominio (beel://guardrails/corrective, …). Nada fiscal se reescribe aquí. Una instantánea del catálogo se incluye en el paquete como respaldo para cuando el host de documentación esté inaccesible; npm run sync:rules es su único escritor, y una prueba falla si se editó a mano. Los antiguos URI beel://guardrails/cancel-vs-rectify, invoice-types y regime-keys aún se resuelven, a los dominios que los reemplazaron.
Las guías de uso de la API — src/guardrails/rules/*.md — cubren lo que no es una regla fiscal pero aún así tropieza a un agente: cómo una línea declara su precio, cómo se configura una serie, sobre qué empresa actúa una operación, cómo leer la validación de NIF y la preparación para emitir, y qué herramienta realiza cada operación de factura. Enlazan a ids de reglas en lugar de reafirmarlos.

Los dominios y guías que aplican se nombran en la descripción de cada herramienta que restringen, por lo que la restricción viaja con la llamada.

2. Aplicado — src/guardrails/validate.ts, comprobado antes de que se envíe 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`
Sin `nif` o `alternative_id` en el destinatario de una factura simplificada (F2)	`SIMPLIFIED_INVOICE_FORBIDS_IDENTIFIED_RECIPIENT`
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 rectificativas pasan por su propia operación, no por `type: CORRECTIVE`	comprobado localmente

3. Explicado — la API de BeeL ya responde bien: su message está escrita para un humano en el idioma de quien llama, error.details lleva los detalles, y el campo type de RFC 7807 enlaza a una página de documentación para ese código exacto. 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 una 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 de hacer bucles en un 403 que necesita un administrador. Cuando el código es uno que cita una regla publicada, el error también nombra esa regla (id, título, enlace). src/guardrails/catalog.ts contiene solo códigos donde uno de esos aplica; cualquier otra cosa pasa, porque una paráfrasis sería peor que el original y se desviaría de él. Los blockers[] anidados de EMISSION_NOT_READY son el caso más claro: llegan como cadenas simples sin mensaje ni enlace, y cada uno sale 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 con el censo de AEAT, el límite 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.

Compartido

Variable	Propósito
`BEEL_BASE_URL`	URL base de la API. Por defecto `https://app.beel.es/api`.
`BEEL_DOCS_URL`	Fuente de documentación para las herramientas de documentación y reglas. Por defecto `https://docs.beel.es`.
`BEEL_REQUEST_TIMEOUT_MS`	Límite máximo para una sola llamada a la API. Por defecto `30000`.
`BEEL_DISABLE_PREFLIGHT`	Establézcalo en `1` para omitir las salvaguardas obligatorias.

Todos los valores predeterminados viven 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 las 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 en sí, por lo que un agente que reintente "crear factura" nunca podrá generar una segunda factura.

Autoalojamiento

El servidor remoto se ejecuta en Cloudflare Workers. Consulte DEPLOY.md para 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
npm run sync:rules   # refresh the bundled rules snapshot from docs.beel.es

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. CI falla si los dos no coinciden, lo que mantiene honesto un contrato vendido. Consulte CONTRIBUTING.md.

El resto del ecosistema de desarrolladores de BeeL

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


API REST	El contrato en sí. 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	Implementar, auditar y mantener una integración de BeeL
Documentación legible por máquina	`llms.txt` para agentes que prefieren leer a adivinar

FAQ

¿Qué es el servidor MCP de BeeL? Un servidor MCP que expone la facturación electrónica VeriFactu española como herramientas que un agente de IA puede llamar — para que Claude, ChatGPT, Cursor o VS Code puedan crear clientes, emitir facturas F1/F2, registrarlas con la AEAT y publicar correctivos R1–R5 en su nombre.

¿Cómo conecto la facturación VeriFactu a Claude / ChatGPT / Cursor? Agregue https://mcp.beel.es/mcp como conector e inicie sesión con su cuenta de BeeL — consulte Inicio rápido. Nada que instalar y sin clave de API que pegar para uso interactivo.

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

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

¿Puedo usarlo sin un agente de IA? Sí — es un servidor MCP estándar, por lo que cualquier cliente compatible con MCP funciona, 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 — consulte CONTRIBUTING.md para saber cómo está organizado el proyecto y qué convenciones son esenciales, y Discussions para preguntas. Los problemas etiquetados como good first issue son un lugar razonable para comenzar. Se espera que todos los participantes sigan el Código de Conducta. Los problemas de seguridad van a security@beel.es en lugar de un problema público; consulte SECURITY.md.

Licencia

MIT © BeeL.

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