ARCA MCP

Servidor MCP para emitir Factura C y Factura E de exportación de servicios de ARCA/AFIP usando Afip SDK, PostgreSQL local y un flujo seguro de preview antes de emitir.

La idea es simple: en vez de tener un bot de Telegram, WhatsApp o una web cerrada, exponés herramientas MCP que cualquier agente compatible puede usar desde Hermes, Claude Desktop, Cursor, VS Code, Windsurf u otro cliente MCP.

Este proyecto está inspirado en el enfoque de Lanuti-Franco/facturador-ARCA: separar el core fiscal de la interfaz. Acá la interfaz es MCP.

Qué Hace

• Emite Factura C para monotributistas mediante WSFE.

• Emite Factura E de exportación de servicios mediante WSFEX.

• Usa Afip SDK para hablar con los web services de ARCA.

• Guarda comprobantes, previews y auditoría en PostgreSQL local.

• Corre con Docker Compose.

• Expone tools MCP por streamable-http.

• Genera PDF con QR obligatorio de ARCA.

• Envía reportes por email al contador con PDFs ya emitidos y CSV opcional.

• Valida CUIT con dígito verificador y acepta DNI.

• Acepta montos en formato argentino o estadounidense: 15.000,50, 15000,50, 15,000.50.

• Tiene alerta de umbral para consumidor final anónimo (UMBRAL_CF).

• Tiene un kill switch de producción: ALLOW_PRODUCTION.

• Obliga a hacer preview antes de emitir una factura real.

Related MCP server: keycae-mcp

Qué No Hace Todavía

• No emite Factura A/B para responsables inscriptos.

• No cubre exportación de mercadería con permisos de embarque.

• No emite Nota de Crédito C todavía.

• No tiene firma WSAA local; usa Afip SDK.

• No reemplaza la revisión de tu contador.

Arquitectura

Cliente MCP / agente / IDE
        |
        | tunel SSH o red privada
        v
arca-mcp container  ->  Afip SDK  ->  ARCA WSFE / WSFEX
        |
        v
postgres-main container

Por defecto el compose publica todo solo en localhost del host:

MCP:        http://127.0.0.1:8000/mcp
PostgreSQL: 127.0.0.1:5432

Eso te permite correrlo en un VPS sin dominio y accederlo por túnel SSH.

Qué Necesitás

1. Ser monotributista con clave fiscal 3 suficiente para administrar certificados y relaciones.

2. Certificado digital de ARCA creado manualmente.

3. Certificado asociado al web service de Facturación Electrónica / WSFE si vas a emitir Factura C.

4. Certificado asociado a Factura Electrónica de Exportación / WSFEX si vas a emitir Factura E.

5. Un punto de venta Web Service para Factura C, distinto al de Comprobantes en Línea.

6. Un punto de venta de exportación para Factura E si vas a usar WSFEX.

7. Cuenta y access_token de Afip SDK.

8. Docker y Docker Compose.

La parte fiscal está explicada paso a paso en docs/arca-setup.md.

Instalación Rápida

git clone https://github.com/ignaciovargasDEV/arca-mcp.git
cd arca-mcp
cp .env.example .env
mkdir -p certs backups

Editá .env con tus datos.

Levantá los servicios:

docker compose up -d --build

Verificá que estén vivos:

docker compose ps

Logs del MCP:

docker compose logs -f arca-mcp

Configuración Para Homologación

Para probar sin emitir comprobantes reales:

POSTGRES_DB=arca_mcp
POSTGRES_USER=arca_mcp_user
POSTGRES_PASSWORD=change-me-long-random-password

AFIP_ACCESS_TOKEN=tu-token-de-afip-sdk
PRODUCTION=false
ALLOW_PRODUCTION=false

TEST_CUIT=20409378472
TEST_PUNTO_VENTA=1

EMISOR_NOMBRE=Tu Nombre
FACTURA_DESCRIPCION=Servicios
CONCEPTO=2

En homologación la confirmación requerida para emitir es:

CONFIRMO EMITIR

Configuración Para Producción

Para comprobantes reales:

PRODUCTION=true
ALLOW_PRODUCTION=false
AFIP_CUIT=tu-cuit-sin-guiones
AFIP_PUNTO_VENTA=tu-punto-de-venta-wsfe
AFIP_PUNTO_VENTA_EXPORTACION=tu-punto-de-venta-wsfex
AFIP_CERT_PATH=/certs/arca.crt
AFIP_KEY_PATH=/certs/arca.key

AFIP_PUNTO_VENTA y AFIP_PUNTO_VENTA_EXPORTACION son configurables. En una instalación pueden ser 3 y 4, en otra 1 y 2, o cualquier número habilitado en ARCA. No copies números de otra persona: verificá tus puntos de venta en ARCA y con config_status / parametros_factura_e.

Montá tus archivos así:

certs/arca.crt  certificado descargado de ARCA
certs/arca.key  private key generada con OpenSSL

No actives ALLOW_PRODUCTION=true hasta haber revisado bien el primer preview.

En producción la confirmación exacta para emitir es:

CONFIRMO EMITIR FACTURA REAL

Flujo Seguro De Emisión

emitir_factura_c y emitir_factura_e no emiten de una. Primero tenés que pedir un preview.

1. Llamás preview_factura_c.

2. Revisás monto, receptor, fecha, modo y advertencias.

3. El MCP devuelve un confirmation_id que dura 10 minutos.

4. Llamás emitir_factura_c con ese confirmation_id y la frase exacta.

Ejemplo conceptual:

preview_factura_c(monto="15000", documento="20-12345678-6", descripcion="Servicios julio")

Después:

emitir_factura_c(confirmation_id="...", confirmacion="CONFIRMO EMITIR FACTURA REAL")

Para exportación de servicios:

preview_factura_e(monto="100", cliente="Cliente Exterior", domicilio_cliente="Madrid, España", pais_destino=200, cuit_pais_cliente=50000000016, moneda="DOL", cotizacion="1200", descripcion="Servicios profesionales")

Después:

emitir_factura_e(confirmation_id="...", confirmacion="CONFIRMO EMITIR FACTURA REAL")

Tools MCP Disponibles

• config_status: revisa DB, token, modo, CUIT, punto de venta y certificados.

• validar_cuit_dni: valida CUIT/DNI y devuelve el tipo de documento ARCA.

• preview_factura_c: genera preview y confirmation_id sin emitir.

• emitir_factura_c: emite usando un confirmation_id válido.

• preview_factura_e: genera preview de Factura E de servicios sin emitir.

• emitir_factura_e: emite Factura E usando un confirmation_id válido.

• parametros_factura_e: consulta catálogos WSFEX.

• resumen_periodo: lista comprobantes emitidos entre dos fechas ISO.

• exportar_csv_periodo: devuelve un CSV separado por ;.

• enviar_reporte_contador: manda resumen, CSV y PDFs ya emitidos por email.

• receptores_recientes: lista receptores identificados ya usados.

Más detalle en docs/tools.md.

La guía específica de Factura E está en docs/factura-e-exportacion.md.

Puntos De Venta

Este proyecto separa los puntos de venta por web service:

• Factura C usa WSFE y AFIP_PUNTO_VENTA.

• Factura E de exportación usa WSFEX y AFIP_PUNTO_VENTA_EXPORTACION.

Los números no son universales. Cada contribuyente debe crear o identificar sus propios puntos de venta en Administración de Puntos de Venta y Domicilios.

Ejemplo ficticio:

AFIP_PUNTO_VENTA=3
AFIP_PUNTO_VENTA_EXPORTACION=4

Si tus puntos de venta son otros, poné tus números. Para validar WSFEX:

parametros_factura_e(catalogo="puntos_venta")

Uso Desde Un VPS Sin Dominio

Si lo corrés en un VPS, no hace falta exponer el puerto a internet. Abrí un túnel SSH desde tu máquina:

ssh -L 8000:127.0.0.1:8000 usuario@tu-vps

Configurá tu cliente MCP con:

http://127.0.0.1:8000/mcp

Hermes

Si usás Hermes, agregás el MCP en ~/.hermes/config.yaml y después corrés /reload-mcp.

La guía está en docs/hermes.md.

Ejemplos Con Hermes Scheduler

Hermes puede usar este MCP tanto para acciones manuales como para tareas recurrentes. La recomendación segura es automatizar previews, reportes y recordatorios, pero no dejar emisiones reales sin confirmación humana.

Ejemplo: reporte mensual al contador:

El primer día de cada mes, usá arca_mcp enviar_reporte_contador para enviar al contador los comprobantes del mes anterior. Usá confirmacion="CONFIRMO ENVIAR EMAIL". No emitas facturas.

Ejemplo: preparar una Factura C recurrente sin emitir:

El día 1 de cada mes, prepará con arca_mcp preview_factura_c una factura por mis servicios mensuales usando los defaults configurados. Mostrame el preview y esperá mi confirmación. No llames emitir_factura_c automáticamente.

Ejemplo: preparar una Factura E recurrente sin emitir:

El día 1 de cada mes, prepará con arca_mcp preview_factura_e la factura de exportación de servicios para mi cliente recurrente usando los defaults del perfil. Mostrame el confirmation_id y esperá mi confirmación exacta. No llames emitir_factura_e automáticamente.

Ejemplo: recordatorio de cierre:

El último día hábil de cada mes, pedime revisar los previews pendientes y recordame enviar el reporte al contador cuando termine de emitir.

Si querés automatizar emisión real, entendé que eso puede generar comprobantes fiscales reales sin revisión humana. Este proyecto lo permite técnicamente solo si se pasa la frase exacta, pero no lo recomienda como default operativo.

Personalización

Podés adaptar el proyecto a tu formato habitual sin tocar código:

• PDFs de referencia privados en private/reference-pdfs/.

• Defaults de facturación en private/billing-profiles.yml.

• Ejemplo versionado en config/billing-profiles.example.yml.

Más detalle en docs/personalizacion-facturas.md.

Hermes puede manejar tareas recurrentes, por ejemplo enviar mensualmente el reporte al contador usando enviar_reporte_contador. El MCP no necesita cron propio para eso.

La guía SMTP y contador está en docs/smtp-contador.md.

Backups

El proyecto trae scripts simples para PostgreSQL:

./scripts/backup-postgres.sh
./scripts/restore-postgres.sh backups/arca_mcp_YYYYmmddTHHMMSSZ.sql.gz

Más detalle en docs/deployment.md.

Seguridad

• No subas .env a git.

• No subas certs/ a git.

• No compartas tu arca.key.

• No expongas /mcp a internet sin autenticación, VPN o túnel.

• No actives ALLOW_PRODUCTION=true hasta que estés listo para emitir real.

• Revisá siempre el preview antes de confirmar.

Más detalle en docs/security.md.

Afip SDK Y Certificados

Este proyecto usa Afip SDK. Eso simplifica mucho la integración con ARCA, pero tenés que saber el tradeoff: para producción, Afip SDK recibe tu certificado y tu private key para autenticar contra ARCA.

Ese certificado no es tu clave fiscal, pero sí permite facturar desde el punto de venta asociado. Si querés evitar terceros por completo, habría que reemplazar Afip SDK por una implementación local de WSAA/WSFE.

Roadmap Posible

• Nota de Crédito C.

• Regeneración de PDF por número de comprobante.

• Aviso de vencimiento del certificado.

• Límite mensual/anual de monotributo.

• Firma WSAA local sin Afip SDK.

• Soporte para Factura A/B.

Disclaimer

Esto no es asesoramiento fiscal. Verificá los comprobantes emitidos, los puntos de venta, los umbrales de consumidor final anónimo, las reglas de exportación de servicios y tu categoría de monotributo con tu contador. Usalo bajo tu propia responsabilidad.

Este proyecto se entrega tal cual, para uso personal o como base de integración. Puede emitir comprobantes fiscales reales si lo configurás en producción y confirmás la emisión. Revisá siempre el preview antes de emitir.

Afip SDK es un servicio de terceros: para producción recibe tu certificado y tu private key para autenticar contra ARCA. Ese certificado no es tu clave fiscal, pero sí permite operar los web services asociados. Si querés cero terceros, tenés que reemplazar esa parte por firma WSAA local.

Licencia

MIT. Usalo, modificalo y compartilo.