BeeL.

Faturamento eletrônico espanhol com VeriFactu (AEAT): emitir faturas, gerenciar clientes, validar NIFs.

Documentação

Servidor MCP BeeL — Facturação eletrónica VeriFactu para agentes de IA

Servidor MCP de facturação eletrónica espanhola com VeriFactu (AEAT): cria, emite e retifica faturas a partir de Claude, ChatGPT, Cursor ou VS Code.
Servidor MCP para facturação eletrónica espanhola com conformidade VeriFactu — emite, corrige e regista faturas na AEAT diretamente do seu agente de IA.
beel.es · Documentação da API · Guia MCP · npm

Um servidor MCP (Model Context Protocol) que permite a um agente de IA emitir faturas eletrónicas espanholas legalmente conformes — registo VeriFactu com a AEAT, tipos de fatura F1/F2, retificações R1–R5, validação de NIF contra o censo, e as chaves de regime que a regulamentação exige. Ligue-o ao Claude, ChatGPT, Cursor ou VS Code e o seu agente pode tratar da faturação espanhola — facturación electrónica e factura electrónica VeriFactu — de ponta a ponta, sem que escreva uma única chamada de API.

Não é um wrapper gerado em torno de uma API. Três coisas tornam-no utilizável por um modelo:

As ferramentas derivam do contrato OpenAPI público, pelo que o esquema de entrada de cada ferramenta é o esquema real da operação — enums, itens de linha, chaves de regime e tudo o resto. A superfície não pode divergir da API.
Uma política de inclusão de ferramentas decide o que um agente deve realmente receber. Transferências binárias, uploads multipart, infraestrutura de webhooks, operações que apenas uma sessão de navegador pode autenticar, e as obsoletas são excluídas por regra, não manualmente.
Salvaguardas fiscais acompanham as ferramentas: os invariantes que um wrapper gerado perderia, tanto como documentação que o modelo lê como como verificações pré-voo que impedem um pedido não conforme antes de se tornar um documento fiscal.

Um único código, dois transportes: o servidor remoto alojado em https://mcp.beel.es/mcp (Streamable HTTP + OAuth — um login por utilizador, nada para instalar), e um servidor local stdio construído a partir deste repositório para uso headless, onde uma chave de API funciona e um login baseado em navegador não.

Início rápido

Adicione https://mcp.beel.es/mcp como conector no Claude, ChatGPT, Cursor ou VS Code e inicie sessão com a sua conta BeeL. Nada para instalar e sem chave de API para gerir: o servidor atua com as suas próprias credenciais, e o fluxo OAuth é descoberto a partir do URL.

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

Essa é toda a configuração para uso interativo. Continue a ler apenas se precisar do servidor local.

Executar localmente

Use o servidor local quando o OAuth não puder: um trabalho agendado que emite faturas, um pipeline de CI, ou qualquer processo headless onde ninguém esteja presente para concluir um login no navegador. Autentica com uma chave de API em vez disso.

Requer 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

Chaves com prefixo beel_sk_test_ são seguras para experimentar; beel_sk_live_ emite documentos fiscais reais.

As versões são publicadas a partir do CI através de publicação confiável do npm, pelo que têm proveniência: o npm regista o commit e o fluxo de trabalho exatos de onde cada build veio. Verifique com npm audit signatures.

Cada versão também é anunciada no MCP Registry como es.beel/mcp, listando ambos os transportes, para que os clientes que navegam no registo encontrem o servidor sem serem apontados para ele. O nome é autenticado por um registo DNS em beel.es, pelo que diz que o servidor vem de nós e não meramente de algum repositório.

Uma listagem anterior sob io.github.beel-es/beel-mcp (v0.2.2) foi retirada quando o nome mudou. Os nomes do registo são identidades em vez de rótulos, pelo que uma renomeação é uma nova entrada em vez de um redirecionamento; ambos apontam para o mesmo pacote npm e o mesmo servidor alojado.

O que fornece

117 ferramentas de API derivadas de openapi/public-api.yaml — faturas, clientes, produtos, faturas recorrentes, séries e configuração fiscal, validação de NIF, empresas.
4 ferramentas sintéticas para as quais a API não tem um único endpoint: beel_docs_search, beel_docs_get, beel_docs_list sobre a documentação, e beel_get_setup_status, que reporta por NIF exatamente o que falta antes de poder emitir e a única próxima ação a tomar.
Recursos de salvaguarda sob beel://guardrails/* — os invariantes fiscais, mais beel://guardrails/errors, um catálogo de cada código de erro com a ação que exige. Os seus resumos são entrelaçados na descrição de cada ferramenta que restringem.
7 prompts de fluxo de trabalho que codificam a ordem segura de operações para os fluxos onde a ordem é o que os torna seguros: issue-invoice (validar NIF → escolher F1/F2 → verificar os portões VeriFactu → emitir), fix-invoice (anular vs corrigir), onboard-nif, setup-representation, invite-member, connect-payments e upgrade-integration.
Visualizador de PDF de fatura inline (MCP Apps): gerar um PDF de fatura abre-o num painel lateral em hosts que o suportam.

Um catálogo gerado de cada ferramenta, com os âmbitos que cada uma requer, vive em docs.beel.es/mcp/tools (npm run tools:catalog).

O que deliberadamente não é uma ferramenta

Transferências binárias (pré-visualização de PDF, ZIP em massa, exportação Excel/CSV), uploads multipart (importação CSV/Holded, submissão de PDF assinado), infraestrutura de webhooks, operações que apenas uma sessão de navegador pode autenticar, e cada operação deprecated. Um agente não pode conduzi-las, e cada uma custa contexto que uma ferramenta utilizável precisa. As regras estão em src/policy/tool-policy.ts.

As salvaguardas fiscais

A faturação eletrónica espanhola tem invariantes que um LLM errará apenas com o esquema — anular uma fatura que deveria ter sido corrigida, usar R1 numa fatura simplificada, editar uma que a AEAT já registou. O servidor aborda isso em três camadas, e a diferença entre elas importa:

1. Consultivo — src/guardrails/rules/*.md, um ficheiro Markdown por tópico: o ciclo de vida da fatura, anular vs retificar, tipos de fatura, linhas de fatura, chaves de regime, numeração de séries, validação de NIF, os portões VeriFactu, contas multi-NIF. Cada um é exposto como um recurso MCP sob beel://guardrails/* e o seu resumo de uma linha é anexado à descrição de cada ferramenta que restringe, para que a restrição viaje com a chamada.

2. Imposto — src/guardrails/validate.ts, verificado antes de o pedido ser enviado, para que um payload inválido nunca consuma sequer uma chave de idempotência:

Verificação	Código
Exatamente um campo de preço por linha	`LINE_UNIT_PRICE_XOR_DECLARED_TOTAL`
Sem desconto num total declarado	`LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT`
Sem retenção de IRPF numa fatura simplificada (F2)	`SIMPLIFICADA_FORBIDS_IRPF`
Sobretaxa de equivalência apenas sob o regime `18`, e `18` apenas com um	`SURCHARGE_REQUIRES_REGIME` / `REGIME_REQUIRES_SURCHARGE`
O formato da série consegue distinguir os seus períodos de reinício	`SERIES_ANNUAL_REQUIRES_YEAR` / `SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR`
A numeração só é semeada na chamada que ativa a empresa	`NUMBERING_REQUIRES_ACTIVATION`
As linhas `SUPLIDO` carregam a sua referência de origem	verificado localmente
Texto de isenção apenas sob o motivo `OTRO`	verificado localmente
As retificações passam pela sua própria operação, não por `type: CORRECTIVE`	verificado localmente

3. Explicado — a API BeeL já responde bem: o seu message é escrito para um humano no idioma do chamador, error.details carrega os detalhes, e o campo RFC 7807 type liga a uma página de documentação para esse código exato (cerca de 357 deles). O servidor retransmite tudo isso intacto, e adiciona apenas as duas coisas que uma resposta não pode carregar: o remédio como uma chamada de ferramenta — a documentação dirige-se a alguém com o painel aberto ("crie uma série nas definições"), um agente precisa de beel_set_default_series — e se repetir pode ajudar, que é o que impede um agente de fazer loop num 403 que precisa de um administrador. src/guardrails/catalog.ts contém apenas códigos onde um desses se aplica; qualquer outra coisa passa, porque uma paráfrase seria pior do que o original e divergiria dele. O blockers[] aninhado de EMISSION_NOT_READY são o caso mais claro: chegam como strings simples sem mensagem e sem ligação, e cada um sai a nomear a ferramenta que o resolve.

A API BeeL é a autoridade em tudo isto. Cada regra imposta espelha uma rejeição que o contrato documenta, pelo que o pré-voo é um subconjunto estrito do que a API recusa: só pode tornar a falha mais rápida e melhor explicada, nunca permitir algo que a API rejeitaria. Regras que dependem de estado do lado do servidor — correspondência do censo AEAT, o teto de €3 000 para F2, se uma série existe — permanecem consultivas de propósito, porque adivinhá-las localmente rejeitaria faturas válidas. Defina BEEL_DISABLE_PREFLIGHT=1 para contornar as verificações locais por completo.

Listas curadas manualmente são ancoradas por testes: cada código catalogado deve ainda aparecer no contrato, cada operationId verificado deve ainda resolver para uma ferramenta real, e cada referência de salvaguarda deve apontar para uma salvaguarda que existe. Uma renomeação de API falha no CI em vez de desligar silenciosamente uma verificação fiscal.

Configuração

Apenas servidor local

Variável	Propósito
`BEEL_API_KEY`	Chave de API. O prefixo seleciona o ambiente: `beel_sk_test_` → Teste, `beel_sk_live_` → Produção.
`BEEL_ENV` / `BEEL_CONFIG_DIR`	Opcional. Com `BEEL_API_KEY` não definido, recorre ao `~/.config/beel/config.json` da CLI (`beel login`); `BEEL_ENV` (`test`/`live`, padrão `test`) escolhe qual chave armazenada.

Partilhado

Variável	Propósito
`BEEL_BASE_URL`	URL base da API. Padrão `https://app.beel.es/api`.
`BEEL_DOCS_URL`	Fonte de documentação para as ferramentas de docs. Padrão `https://docs.beel.es`.
`BEEL_REQUEST_TIMEOUT_MS`	Limite máximo para uma única chamada de API. Padrão `30000`.
`BEEL_DISABLE_PREFLIGHT`	Defina para `1` para saltar as salvaguardas impostas.

Cada padrão vive em src/shared/defaults.ts; nada é codificado duas vezes. As variáveis de implementação remota estão documentadas em DEPLOY.md.

O servidor inicia e lista ferramentas sem quaisquer credenciais — só dá erro quando uma ferramenta de API é realmente chamada. Os pedidos POST carregam um Idempotency-Key estável derivado do próprio pedido, para que um agente a repetir "criar fatura" nunca possa cunhar uma segunda fatura.

Auto-alojamento

O servidor remoto corre em Cloudflare Workers. Veja DEPLOY.md para o espaço de nomes KV, o cliente OAuth que a BeeL deve ter registado, e os segredos envolvidos.

Desenvolvimento

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 é uma cópia gerada do contrato da API, e openapi/spec.lock.json regista a sua versão, contagem de operações e hash. O CI falha se os dois divergirem, o que mantém um contrato vendido honesto. Veja CONTRIBUTING.md.

O resto do ecossistema de desenvolvimento BeeL

Tudo abaixo deriva do mesmo contrato OpenAPI, pelo que o vocabulário — tipos de fatura, chaves de regime, séries, estados VeriFactu — é idêntico onde quer que o encontre.


API REST	O próprio contrato. Tudo o resto é uma projeção dele
CLI	A mesma superfície a partir de um terminal, sandbox por padrão
Nó n8n	Faturação dentro de um fluxo de trabalho no-code
Plugin Claude Code	Implemente, audite e mantenha uma integração BeeL
Documentação legível por máquina	`llms.txt` para agentes que preferem ler a adivinhar

FAQ

O que é o servidor MCP BeeL? Um servidor MCP que expõe a faturação eletrónica espanhola VeriFactu como ferramentas que um agente de IA pode chamar — para que Claude, ChatGPT, Cursor ou VS Code possam criar clientes, emitir faturas F1/F2, registá-las na AEAT e lançar correções R1–R5 em seu nome.

Como ligo a faturação VeriFactu ao Claude / ChatGPT / Cursor? Adicione https://mcp.beel.es/mcp como conector e inicie sessão com a sua conta BeeL — consulte Início rápido. Não é necessário instalar nada e não precisa de colar chaves de API para utilização interativa.

É realmente compatível com VeriFactu? Sim. As faturas são registadas na AEAT ao abrigo do VeriFactu, a numeração e as séries seguem a regulamentação, e as salvaguardas fiscais impedem pedidos não conformes antes de se tornarem um documento fiscal.

VeriFactu ou TicketBAI? Este servidor tem como alvo o VeriFactu, o sistema nacional da AEAT. O TicketBAI (o regime do País Basco) está fora do âmbito.

Posso usá-lo sem um agente de IA? Sim — é um servidor MCP padrão, pelo que qualquer cliente compatível com MCP funciona, e a mesma superfície de faturação está disponível como API REST, CLI e nó n8n.

Contribuir

Relatórios de erros e pedidos de pull são bem-vindos — consulte CONTRIBUTING.md para saber como o projeto está organizado e quais as convenções essenciais, e Discussões para perguntas. As questões etiquetadas como good first issue são um bom ponto de partida. Espera-se que todos os participantes sigam o Código de Conduta. Questões de segurança devem ser enviadas para security@beel.es em vez de uma questão pública; consulte SECURITY.md.

Licença

MIT © BeeL.

_{beel.es · Documentação · Guia do MCP}