# BeeL

BeeL — an MCP server for issuing Spanish electronic invoices with VeriFactu registration at AEAT. Your agent validates NIFs, creates F1/F2 invoices and R1–R5 corrections straight from Claude Code, Cursor or VS Code.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 2 repo stars
- Author: beel-es
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/beel-es/beel-mcp
- Updated: 2026-10-21
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/beel

## What it does

The server exposes 125 tools built from BeeL's public OpenAPI contract: invoice issuance, customer and product management, NIF validation against the census, tax regime configuration. Input schemas include enums, regime keys and line-item structures — all from the real API, no drift. Seven synthetic tools cover documentation search, the fiscal rules catalogue and NIF readiness checks.

Runs in two modes: a remote server at `https://mcp.beel.es/mcp` with OAuth login (nothing to install) and a local stdio server via `npx @beel_es/mcp` for automation where API keys work and browser logins do not. Keys prefixed `beel_sk_test_` are safe to experiment with; `beel_sk_live_` issue real fiscal documents.

Built-in guardrails stop a request before it becomes a document if regulatory invariants break. Resources under `beel://guardrails/*` carry fiscal rules by domain, an error code catalogue and seven workflow prompts: issue invoice, fix invoice, onboard NIF, connect payments.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://mcp.beel.es/mcp`
- Environment variables: `BEEL_API_KEY`, `BEEL_ENV` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http mcp https://mcp.beel.es/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env BEEL_API_KEY=<BEEL_API_KEY> --env BEEL_ENV=<BEEL_ENV> --transport stdio beel -- npx -y @beel_es/mcp
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add beel --url https://mcp.beel.es/mcp
```

2. **Platform CLI**
```bash
codex mcp add beel --env BEEL_API_KEY=<BEEL_API_KEY> --env BEEL_ENV=<BEEL_ENV> -- npx -y @beel_es/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "beel": {
            "url": "https://mcp.beel.es/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "beel": {
            "command": "npx",
            "args": [
                "-y",
                "@beel_es/mcp"
            ],
            "env": {
                "BEEL_API_KEY": "<BEEL_API_KEY>",
                "BEEL_ENV": "<BEEL_ENV>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "beel": {
            "type": "http",
            "url": "https://mcp.beel.es/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "beel": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@beel_es/mcp"
            ],
            "env": {
                "BEEL_API_KEY": "<BEEL_API_KEY>",
                "BEEL_ENV": "<BEEL_ENV>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http beel https://mcp.beel.es/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e BEEL_API_KEY=<BEEL_API_KEY> -e BEEL_ENV=<BEEL_ENV> beel npx -y @beel_es/mcp
```
Replace <…> with your own values

## When to use it
- Issue a Spanish electronic invoice with VeriFactu registration at AEAT
- Validate a counterparty's NIF against the tax authority census
- Create an R1–R5 corrective invoice that meets regulatory requirements
- Configure tax regimes and document series for a company

## Example prompts
- Validate NIF ES12345678A and create an F1 invoice for 1200 euros
- Issue an R2 correction for invoice INV-2024-001 and register it with VeriFactu
- Show what needs to be configured for NIF ESB87654321 before it can issue invoices

## Similar
- [Factuarea](https://affpapa.org/en/nevibecode/mcp/factuarea.md) — MCP server
- [BORME API](https://affpapa.org/en/nevibecode/mcp/borme-api.md) — MCP server
- [Hellobooks](https://affpapa.org/en/nevibecode/mcp/hellobooks.md) — MCP server · 1748 installs
- [VAT Validator MCP](https://affpapa.org/en/nevibecode/mcp/vat-validator-mcp.md) — MCP server · 42 installs
- [invoice-tax-checklist](https://affpapa.org/en/nevibecode/skills/invoice-tax-checklist.md) — skill · ★ 12746 repo stars
- [PropertyList - Official](https://affpapa.org/en/nevibecode/mcp/propertylist-official.md) — MCP server · 976 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
