🧾 Facturama MCP Server

Servidor MCP (Model Context Protocol) basado en FastMCP 3.x que expone la API de Facturama como herramientas para agentes LLM (Claude Desktop, Claude Code, Cursor, y cualquier cliente MCP). Cubre toda la operación de facturación electrónica CFDI 4.0 en México.

Tabla de contenidos

• ¿Qué hace?
• Características
• Herramientas disponibles
• Instalación
• Configuración
• Uso
  • Claude Desktop
  • Claude Code
  • Cursor
  • VS Code
  • n8n, Make y Zapier
• Ejemplos de uso
• Particularidades de la API de Facturama
• Estructura del proyecto
• Desarrollo
• Despliegue
• Troubleshooting
• Roadmap
• Stack técnico
• Contribuir

¿Qué hace?

Permite que un agente de IA (o cualquier cliente MCP) pueda operar la facturación electrónica completa con lenguaje natural:

• 🧾 Crear, consultar, cancelar y descargar CFDIs (Ingreso, Egreso, Pago)
• 💸 Generar Complementos de Pago (REP 2.0) para facturas PPD
• 👥 CRUD de clientes y productos del catálogo
• 📚 Buscar en catálogos del SAT sin salir del agente
• 📧 Enviar facturas por email al receptor
• 💰 Manejar descuentos, retenciones, multiconcepto, monedas extranjeras

Ejemplo de prompt al agente:

"Hazme una factura para EMPRESA EJEMPLO, RFC ABC010101AAA, régimen 612, CP 78290. Un concepto: Software, $500 + IVA 16%. Mándamela por email a contabilidad@ejemplo.com"

El agente usa las herramientas del MCP para construir el CFDI correcto, timbrarlo y enviarlo.

Características

✅ CFDI 4.0 — Ingreso, Egreso (notas de crédito), Traslado, Pago ✅ Complemento de Pagos REP 2.0 — para facturas PPD ✅ Multiconcepto — múltiples ítems en una sola factura ✅ Descuentos por concepto — con cálculo automático de bases imponibles ✅ Retenciones e IVA traslado — IVA, ISR, IEPS ✅ Cancelación con todos los motivos SAT — incluyendo motivo 01 con UUID sustitución ✅ CRUD completo — clientes y productos ✅ Búsqueda en catálogos SAT — productos, unidades, regímenes, usos CFDI, formas de pago, monedas, códigos postales ✅ Envío por email automático — con confirmación explícita ✅ Descargas PDF / XML / HTML — guardadas a disco ✅ Emisor tomado de la cuenta — el modelo no puede inventarse en nombre de quién se factura ✅ Guardarraíles de producción — dos cerrojos independientes antes de timbrar con valor fiscal

Herramientas disponibles (27 tools)

Módulo 0 — Emisión en una sola llamada (1 tool)

Módulo 1 — CFDI (7 tools)

Control fino del comprobante, para lo que no cubre facturama_factura_emitir.

Módulo 2 — Clientes (5 tools)

Módulo 3 — Productos (5 tools)

Módulo 4 — Catálogos SAT (7 tools)

Módulo 5 — Cuenta (2 tools)

Instalación

Estado: el paquete todavía no está publicado en PyPI. Hasta que lo esté, usa la instalación desde el repositorio que se describe más abajo; los comandos con uvx facturama-mcp funcionarán en cuanto se publique la v1.0.

Requisitos

• Python 3.11+ — salvo con el bundle .mcpb o con Docker, que lo llevan dentro
• Credenciales de Facturama, de sandbox o de producción

Las credenciales de sandbox son tuyas, no genéricas. No existe un usuario de demo público: cada cuenta tiene las suyas y se piden a Facturama. Si ves un 401 Credenciales inválidas, es esto.

Cuatro formas, según quién lo instale

Bundle para Claude Desktop

Descarga facturama-facturacion.mcpb de la última versión publicada y arrástralo a Claude Desktop. Te pedirá usuario, contraseña y entorno en un formulario. No hace falta Python ni tocar ningún archivo de configuración.

Para construirlo tú mismo: ./mcpb/construir.sh

Desde PyPI

uvx facturama-mcp          # ejecuta sin instalar nada permanente
# o
pip install facturama-mcp  # instalación normal

Con Docker

docker run --rm -p 8000:8000 \
  -e FACTURAMA_USER=tu_usuario \
  -e FACTURAMA_PASSWORD=tu_contraseña \
  facturama/mcp

Arranca en HTTP (http://localhost:8000/mcp), que es lo que necesitan n8n, Make y Zapier. Las credenciales van por variables de entorno y nunca dentro de la imagen.

Desde el repositorio

git clone https://github.com/facturamamx/mcp-facturacion.git
cd mcp-facturacion
uv sync
cp .env.example .env      # y edítalo con tus credenciales
uv run facturama-mcp

Configuración

Cuatro variables de entorno, y solo las dos primeras son obligatorias:

Por qué hay dos cerrojos para producción. FACTURAMA_ENV=production no basta por sí solo: hace falta además FACTURAMA_ALLOW_PRODUCTION=true, que solo puede poner una persona en el entorno del servidor, y una confirmación explícita en cada llamada que timbre. Timbrar es irreversible y consume folios, así que llegar ahí por descuido no debería ser posible.

Otras variables opcionales: FACTURAMA_TIMEOUT (30 s), FACTURAMA_MAX_RETRIES (3), FACTURAMA_DOWNLOAD_DIR (./downloads) y FACTURAMA_MCP_TRANSPORT (stdio o http).

Uso

Claude Desktop

Lo más sencillo es el bundle .mcpb de arriba. Si prefieres configurarlo a mano, edita ~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%\Claude\claude_desktop_config.json en Windows:

{
  "mcpServers": {
    "facturama": {
      "command": "uvx",
      "args": ["facturama-mcp"],
      "env": {
        "FACTURAMA_USER": "tu_usuario",
        "FACTURAMA_PASSWORD": "tu_contraseña",
        "FACTURAMA_ENV": "sandbox"
      }
    }
  }
}

💡 Si Claude Desktop no encuentra uvx, pon su ruta absoluta (which uvx): la aplicación no hereda el PATH de tu terminal.

Claude Code

claude mcp add facturama \
  --env FACTURAMA_USER=tu_usuario \
  --env FACTURAMA_PASSWORD=tu_contraseña \
  --env FACTURAMA_ENV=sandbox \
  -- uvx facturama-mcp

Cursor

En ~/.cursor/mcp.json, o en .cursor/mcp.json dentro del proyecto:

{
  "mcpServers": {
    "facturama": {
      "command": "uvx",
      "args": ["facturama-mcp"],
      "env": {
        "FACTURAMA_USER": "tu_usuario",
        "FACTURAMA_PASSWORD": "tu_contraseña",
        "FACTURAMA_ENV": "sandbox"
      }
    }
  }
}

VS Code

En .vscode/mcp.json. VS Code sabe pedir los secretos al arrancar, así que no hace falta escribirlos en el archivo:

{
  "inputs": [
    {
      "id": "facturama-password",
      "type": "promptString",
      "description": "Contraseña de la API de Facturama",
      "password": true
    }
  ],
  "servers": {
    "facturama": {
      "command": "uvx",
      "args": ["facturama-mcp"],
      "env": {
        "FACTURAMA_USER": "tu_usuario",
        "FACTURAMA_PASSWORD": "${input:facturama-password}",
        "FACTURAMA_ENV": "sandbox"
      }
    }
  }
}

n8n, Make y Zapier

Estos no ejecutan procesos locales: necesitan una URL. Levanta el servidor en HTTP y apúntalos a ella.

docker run -d -p 8000:8000 \
  -e FACTURAMA_USER=tu_usuario \
  -e FACTURAMA_PASSWORD=tu_contraseña \
  --name facturama-mcp facturama/mcp

En n8n, añade un nodo MCP Client con la URL http://localhost:8000/mcp y transporte HTTP Streamable.

⚠️ Ese contenedor expone tus credenciales de facturación a quien alcance el puerto. Publícalo solo dentro de tu red, detrás de un proxy con autenticación, y nunca directamente a internet. El servidor remoto con OAuth llega en la v1.5.

Ejemplos de uso

1. Factura simple (1 concepto, IVA 16%)

"Factura 2 servicios de facturación a 1.000 € cada uno al RFC EKU9003173C9, folio FLUJO-1."

→ Una sola llamada a facturama_factura_emitir. Si el cliente ya está dado de alta, no hace falta nada más: su razón social, régimen y CP salen de su ficha, el emisor y el lugar de expedición de la cuenta, y la clave del SAT de la descripción. Devuelve el UUID timbrado junto con las claves que resolvió, para poder revisarlas.

Con control total del comprobante —o para un CFDI que no sea de ingreso— se usa facturama_cfdi_crear, pasando cada clave del SAT explícitamente.

2. Factura con múltiples conceptos y descuento

"Crea factura para [datos receptor]. 3 conceptos: (1) Hosting $500, (2) Dominio $200 con descuento de $50, (3) Certificado SSL $100. Todos con IVA 16%."

→ Usa el campo Discount por concepto. La base imponible se calcula como subtotal − descuento antes del IVA.

3. Factura de honorarios con retención

"Genera factura para [datos]. 1 concepto: Consultoría legal $10,000. Aplica IVA 16% traslado y retención de ISR 10%."

→ Resultado: subtotal $10,000 + IVA $1,600 − ISR $1,000 = $10,600.

4. Cancelar y sustituir un CFDI

"Cancela el CFDI con id swkZKaX... motivo 01 y sustitúyelo por el UUID 4e805b06-..."

→ Llama facturama_cfdi_cancelar con motivo="01" y uuid_sustitucion.

5. Complemento de pago (PPD)

"Crea complemento de pago para liquidar la factura UUID bb993a7f-... folio 21 por $5,800 mediante transferencia bancaria el 2026-05-06."

→ Llama facturama_cfdi_crear_pago con el array de pagos y documentos relacionados.

6. Buscar clave SAT

"¿Cuál es la clave SAT para servicios de marketing digital?"

→ El agente prueba buscar_producto_sat("publicidad") y sugiere 82101603 - Publicidad en internet.

7. Crear cliente desde constancia fiscal

"Aquí está la constancia fiscal de mi cliente [adjunto PDF]. Crea el cliente en el catálogo y emite una factura por $1,000."

→ El agente extrae los datos del PDF (RFC, nombre, régimen, CP) y llama facturama_clientes_crear + facturama_cfdi_crear.

Particularidades de la API de Facturama

⚠️ Estos son hallazgos validados en producción que no están claramente documentados. Anótalos para tu equipo.

1. Validación nombre↔RFC (CFDI 4.0)

Desde CFDI 4.0, el SAT valida que el receptor_nombre coincida exactamente con el nombre registrado para ese RFC en su cédula fiscal.

• ❌ RFC inventado + nombre ficticio → 400 Bad Request
• ✅ RFC real con nombre tal cual SAT → OK
• ✅ RFCs genéricos del SAT siempre funcionan:
  • XAXX010101000 — Público en general
  • XEXX010101000 — Receptor extranjero

2. Endpoints CFDI ≠ /api-lite/Cfdi

Documentación parcial sugiere /api-lite/Cfdi/.... Esos endpoints no existen en producción. Los reales son:

POST /3/cfdis toma el emisor y el CSD de la cuenta autenticada. La variante /api-lite/3/cfdis es para revendedores que timbran en nombre de varios contribuyentes y exige un nodo Issuer en el payload; queda fuera del alcance de la v1.0, que factura siempre en nombre del titular de las credenciales.

3. PUT estricto en clientes y productos

La API rechaza payloads parciales en PUT /Client/{id} y PUT /Product/{id}:

• Exige todos los campos requeridos del modelo
• Rechaza strings vacíos en campos opcionales (CuentaPredial: "" falla)

Este MCP implementa automáticamente GET → merge → clean → PUT, así que solo pasas los campos a cambiar (facturama_clientes_actualizar, facturama_productos_actualizar).

4. CFDI tipo P (Pago) tiene un payload muy distinto

• ❌ NO debe llevar Items ni PaymentForm a nivel raíz
• ✅ CfdiUse debe ser CP01 obligatoriamente
• ✅ Toda la info real va en Complemento.Payments
• La herramienta facturama_cfdi_crear_pago aplica esto automáticamente.

5. Endpoints DELETE para clientes

• ❌ DELETE /Client/{id} → 404
• ✅ DELETE /api-lite/client/{id} → 200

(El MCP usa el correcto.)

6. Comportamiento del sandbox vs producción

El sandbox NO tiene validez fiscal pero SÍ envía correos reales. Cuidado con los destinatarios.

7. Búsqueda sensible a acentos

El catálogo SAT del endpoint /catalogs/ProductsOrServices distingue acentos:

buscar_producto_sat("consultoria")    → []           ❌
buscar_producto_sat("consultoría")    → 4 resultados ✅
buscar_producto_sat("80101500")       → 1 resultado  ✅ (clave directa)

8. Límite de envíos por email

Facturama bloquea el reenvío múltiple de la misma factura al mismo email (anti-spam). Si necesitas reenviar, crea un CFDI nuevo o cambia de destinatario.

Mensaje de error explícito: {"success": false, "msj": "Has alcanzado el límite de envíos para esta factura."}

9. Header Content-Type: application/json (sin charset)

Algunos endpoints rechazan Content-Type: application/json; charset=utf-8 (lo que httpx envía por default). El MCP envía solo application/json.

Estructura del proyecto

mcp-facturacion/
├── src/facturama_mcp/
│   ├── server.py          # Las 27 herramientas MCP
│   ├── client.py          # Cliente HTTP: reintentos, timeouts, credenciales
│   ├── config.py          # Configuración diferida desde el entorno
│   ├── account.py         # Emisor y lugares de expedición, desde la cuenta
│   ├── resolucion.py      # Resolución de claves del SAT y de clientes
│   ├── respuestas.py      # Paginación, truncado y formato de las respuestas
│   ├── catalogs.py        # Catálogos del SAT con caché por proceso
│   ├── validators.py      # Validación estructural antes de llamar a la API
│   ├── errors.py          # Traducción de errores de la API
│   └── cli.py             # Punto de entrada `facturama-mcp`
├── tests/
│   ├── fixtures/          # Respuestas capturadas del sandbox real
│   ├── sandbox_falso.py   # Sirve esas capturas sin red
│   └── capturar_fixtures.py
├── mcpb/                  # Bundle para Claude Desktop
├── server.json            # Metadatos para el MCP Registry
├── Dockerfile
└── ROADMAP-v1.md          # Plan, decisiones cerradas y su porqué

Por dónde empezar a leer

• server.py — cada herramienta es una función async con @mcp.tool().
• ROADMAP-v1.md §6 — las decisiones de diseño y, sobre todo, por qué se tomaron. Ahorra re-litigar cosas ya discutidas.
• tests/sandbox_falso.py — reproduce las rarezas reales de la API. Si algo te sorprende del código, probablemente esté explicado ahí.

Desarrollo

uv sync                    # instalar
uv run facturama-mcp       # arrancar en stdio

# En HTTP, para n8n o pruebas remotas
FACTURAMA_MCP_TRANSPORT=http uv run facturama-mcp

Pruebas

uv run pytest -m "not sandbox"   # 310 pruebas, sin red ni credenciales
uv run pytest -m sandbox         # contrato contra la API real (necesita .env)
uv run ruff check src/ tests/
uv run mypy src/facturama_mcp/

Las pruebas offline corren contra capturas reales del sandbox, no contra mocks escritos a mano. Si la API cambia, se recapturan:

uv run python tests/capturar_fixtures.py

El motivo está en ROADMAP-v1.md §6.12, y se resume en que los fallos que ha tenido este servidor respondían todos 200: un mock inventado los habría dado por buenos.

Inspeccionar las herramientas

npx @modelcontextprotocol/inspector uv run facturama-mcp

Despliegue

Para uso personal o de escritorio no hace falta desplegar nada: el bundle .mcpb o uvx facturama-mcp corren en el equipo de cada persona con sus propias claves. Esto es para compartir el servidor con un equipo o conectarlo a n8n, Make o Zapier.

Docker

docker run -d --name facturama-mcp -p 8000:8000 \
  -e FACTURAMA_USER=tu_usuario \
  -e FACTURAMA_PASSWORD=tu_password \
  -e FACTURAMA_ENV=production \
  -e FACTURAMA_ALLOW_PRODUCTION=true \
  --restart unless-stopped \
  facturama/mcp

Antes de poner FACTURAMA_ALLOW_PRODUCTION=true, lee esto. Ese contenedor puede timbrar comprobantes con valor fiscal ante el SAT, y quien alcance el puerto puede hacerlo. Hoy el servidor no autentica a quien se conecta: da por hecho que corre en el equipo de su dueño. Si lo expones en red:

• Detrás de un proxy con TLS y autenticación, nunca directo a internet.
• Solo en la red interna, sin publicar el puerto al exterior.
• En sandbox mientras estés probando la integración.

El servidor remoto pensado para varios usuarios, con OAuth 2.1 y aislamiento por cuenta, llega en la v1.5. Hasta entonces, esto es un despliegue de un solo inquilino disfrazado de servicio.

Comprobar que está sano

curl -s http://localhost:8000/mcp -H 'Accept: text/event-stream' | head -1
docker logs facturama-mcp

La imagen trae un HEALTHCHECK que comprueba que el servidor puede listar sus herramientas, no solo que el puerto conteste.

Troubleshooting

"401 Unauthorized" al iniciar el servidor

• Verifica que .env tenga las credenciales correctas
• Si el password tiene caracteres especiales (&, @, $), está bien tal cual — NO escapes
• Verifica que FACTURAMA_ENV esté en sandbox o production correctamente

"El campo Nombre del receptor, debe pertenecer al nombre asociado al RFC"

• El RFC inventado no pasa validación SAT (CFDI 4.0)
• Usa un RFC real con su nombre correcto, o un RFC genérico (XAXX010101000)

"Has alcanzado el límite de envíos para esta factura"

• Facturama bloquea reenvíos al mismo email
• Crea una nueva factura o usa otro destinatario

La tool no aparece en Claude Code/Desktop/Cursor

• Verifica que el config apunte a uv con ruta absoluta (which uv)
• Reinicia el cliente tras editar el config
• En Claude Code: /mcp te muestra los servidores conectados
• Revisa que el .env esté presente en el directorio del servidor

Búsqueda en SAT devuelve vacío

• ¿Tiene acentos? consultoria ❌ vs consultoría ✅
• Si conoces la clave SAT, búscala directa: buscar_producto_sat("80101500")

CSD o "no encontrado el certificado del emisor"

• El usuario sandbox lovableapi SÍ tiene CSD para EKU9003173C9
• Si usas otro RFC emisor, asegúrate de tener su CSD configurado en Facturama
• El MCP hace fallback automático a la API regular si la Lite falla por CSD

127 command not found: uv

• Falta instalar uv o no está en el PATH
• Usa la ruta absoluta en el config: which uv te la dice

Roadmap

v0.3 — En curso

• Tests automatizados — pytest + coverage > 80%
• Dockerfile + docker-compose
• Auth en HTTP remoto — token Bearer compartido
• Resources MCP — plantillas de CFDIs comunes
• Logging estructurado — JSON logs

v0.4 — Planeado

• Nómina — CFDIs con complemento 1.2
• Carta Porte 3.1 — Para transportistas
• Multiemisor — Soporte para múltiples RFCs emisores en una sesión
• Comercio Exterior — Complemento para exportaciones
• Reportes fiscales — Resúmenes por período

v0.5 — Futuro

• Webhooks — Notificaciones de cancelación/aceptación
• Validador XML — Verificación previa antes de timbrar
• Plantillas reutilizables — Para clientes y productos frecuentes

Completado ✅

• CFDI 4.0 (Ingreso, Egreso, Pago)
• CRUD Clientes y Productos
• Catálogos del SAT
• Cancelaciones (todos los motivos 01-04)
• Multi-concepto, descuentos, retenciones
• Envío por email con confirmación
• Descargas PDF/XML/HTML
• Complemento de Pagos REP 2.0
• Validación end-to-end con 24 herramientas

Stack técnico

Decisiones de diseño

• Async I/O end-to-end con httpx.AsyncClient para no bloquear en operaciones de red.
• Decimal con ROUND_HALF_UP para todos los cálculos monetarios (compatible con regla SAT).
• Pydantic models para Item y Tax con tipado fuerte que se traduce a JSON Schema MCP automáticamente.
• Fallback automático a API regular cuando API Lite falla por falta de CSD.
• GET → merge → clean → PUT en updates para evitar payloads parciales rechazados por la API.

Contribuir

Pull Requests / Merge Requests bienvenidos.

Flujo recomendado

1. Fork del repo
2. Crea una branch: feature/mi-tool o fix/bug-x
3. Implementa + prueba localmente con MCP Inspector o Python directo
4. Push + abre PR/MR a main
5. Espera revisión de un Maintainer

Convenciones de commits

feat: nueva funcionalidad
fix: corrección de bug
docs: cambios en documentación
chore: mantenimiento (deps, configs)
test: agregar/modificar tests
refactor: cambios sin alterar comportamiento

Reportar bugs

Abre un issue con:

• Versión del MCP (git rev-parse HEAD)
• Comando ejecutado o prompt al agente
• Output esperado vs output real
• Logs (con HTTPX_LOG_LEVEL=DEBUG si es problema HTTP)

Licencia

(Por definir — sugerencia: MIT o Apache 2.0)

Créditos

Desarrollo y validación: Antonio Tembleque (@facturamamx) — Facturama Engineering.

Hallazgos de bugs en la API documentados durante validación end-to-end con todas las 24 herramientas en sandbox.

Soporte

• Issues / bugs: abrir issue en este repo
• Documentación API Facturama: https://apisandbox.facturama.mx/docs
• Documentación FastMCP: https://gofastmcp.com
• Especificación MCP: https://modelcontextprotocol.io