arca-mcp

Servidor MCP (Model Context Protocol) que permite a agentes de IA emitir facturas electrónicas en ARCA/AFIP (Argentina) usando el web service WSFEv1, conectándose directo a los servicios oficiales de ARCA — sin APIs intermediarias.

La autenticación (WSAA con certificado X.509) y las operaciones de WSFEv1 las maneja un cliente ARCA vendorizado en src/arca/ — código derivado de los SDKs MIT de ramiidv que mantenemos y modificamos directamente (incluye un fix propio del header SOAPAction que el upstream rompía; ver src/arca/README.md). Este proyecto expone esas capacidades como tools MCP con esquemas validados, mensajes de error accionables y enriquecido de datos (URL del QR oficial).

⚠️ Software fiscal. En modo producción este servidor emite comprobantes fiscales reales e irreversibles. Probá siempre primero en homologación. No es software oficial de ARCA y se provee sin garantías.

Tools disponibles

| Tool | Qué hace | |------|----------| | arca_estado_servidor | Health-check de los servidores de ARCA (FEDummy). No requiere autenticación. | | arca_ultimo_autorizado | Último número de comprobante autorizado para un punto de venta y tipo. | | arca_consultar_comprobante | Datos de un comprobante ya emitido (CAE, importes, fechas). | | arca_consultar_cuit | Datos de un contribuyente en el padrón (A13 básico o A5 detallado). | | arca_parametros | Tablas de parámetros vigentes (tipos de comprobante, alícuotas IVA, monedas, condiciones IVA, puntos de venta, cotización, etc.). | | arca_emitir_factura | Emite una factura A/B/C/M (y FCE) y solicita el CAE. Devuelve CAE, vencimiento, importes y URL del QR. | | arca_emitir_nota | Emite una nota de crédito o débito asociada a un comprobante original. | | arca_generar_pdf | Genera el PDF (A4) de la representación impresa válida AFIP del comprobante (emisor, receptor, ítems, totales, CAE y QR). |

Flujo recomendado para el agente: arca_estado_servidor → (opcional) arca_parametros / arca_ultimo_autorizado → arca_emitir_factura / arca_emitir_nota → arca_generar_pdf.

Requisitos

• Node.js ≥ 18 (probado con Node 23).
• Un certificado digital de ARCA asociado al web service wsfe (ver más abajo).
• Tu CUIT de contribuyente.

Instalación

Como usuario (desde npm): no hace falta instalar nada manualmente; el host MCP lo ejecuta con npx (ver Uso con clientes MCP). Requiere Node ≥18 y, para el PDF, un Chrome/Chromium instalado.

# Opcional: instalación global del binario
npm install -g @mdrzazga/arca-mcp

Para desarrollo (desde el repo):

npm install
npm run build

Generar el certificado de ARCA

El certificado es un trámite manual en ARCA (no se puede automatizar). Resumen:

1. Generar clave privada y CSR (Certificate Signing Request):

   openssl genrsa -out private.key 2048
   openssl req -new -key private.key -subj "/C=AR/O=TU_RAZON_SOCIAL/CN=arca-mcp/serialNumber=CUIT TU_CUIT" -out pedido.csr

2. Subir el CSR y descargar el certificado (.crt):
   • Homologación: ARCA → WSASS (Autogestión de Certificados Homologación) → crear un DN y un alias, subir el .csr, descargar el .crt.
   • Producción: ARCA con Clave Fiscal → Administración de Certificados Digitales → crear alias, subir el .csr, descargar el .crt.
3. Asociar el web service wsfe al certificado/alias:
   • Producción: ARCA → Administrador de Relaciones de Clave Fiscal → Nueva relación → buscar el servicio "Facturación Electrónica" (wsfe) → seleccionar el certificado como representante.
   • Homologación: el alias en WSASS ya queda habilitado para los servicios de testing.
4. Guardá private.key y cert.crt en ./secrets/ (ignorado por git).

El mismo procedimiento aplica para habilitar el padrón A5 si querés usar arca_consultar_cuit con detalle=true.

Configuración

Copiá .env.example a .env y completá tus datos (o exportá las variables en el entorno donde corra el cliente MCP):

cp .env.example .env

| Variable | Requerida | Descripción | |----------|-----------|-------------| | ARCA_CUIT | ✅ | CUIT del contribuyente (11 dígitos, sin guiones). | | ARCA_CERT_PATH | ✅* | Ruta al certificado .crt (PEM). | | ARCA_KEY_PATH | ✅* | Ruta a la clave privada .key (PEM). | | ARCA_CERT / ARCA_KEY | — | Alternativa inline al contenido PEM (en vez de las rutas). | | ARCA_PRODUCTION | — | true = producción. Cualquier otro valor / ausente = homologación (default). | | ARCA_TOKEN_TTL_MIN | — | TTL del token WSAA en minutos (default 720). | | ARCA_TIMEOUT_MS | — | Timeout HTTP en ms (default 30000). | | ARCA_RETRIES | — | Reintentos ante errores transitorios (default 1). |

* Podés usar ARCA_CERT_PATH/ARCA_KEY_PATH o ARCA_CERT/ARCA_KEY (inline).

Uso con clientes MCP

Claude Desktop / Claude Code

Agregá el servidor a tu configuración MCP (claude_desktop_config.json o .mcp.json). Vía npm con npx (recomendado):

{
  "mcpServers": {
    "arca": {
      "command": "npx",
      "args": ["-y", "@mdrzazga/arca-mcp"],
      "env": {
        "ARCA_CUIT": "20123456789",
        "ARCA_CERT_PATH": "/ruta/absoluta/a/secrets/cert.crt",
        "ARCA_KEY_PATH": "/ruta/absoluta/a/secrets/private.key",
        "ARCA_PRODUCTION": "false",
        "ARCA_EMISOR_FILE": "/ruta/absoluta/a/emisor.json"
      }
    }
  }
}

Para correr desde un clone local en vez de npm, usá "command": "node" con "args": ["/ruta/absoluta/a/arca-mcp/dist/index.js"].

Reiniciá el cliente y el agente verá las 8 tools arca_*.

Desarrollo

npm run dev        # ejecuta con tsx en modo watch (requiere las env vars cargadas)
npm run typecheck  # chequeo de tipos

El transport es stdio: no escribas nada a stdout desde hooks externos, está reservado para el protocolo MCP (los logs van a stderr).

Ejemplo de emisión

Pedido típico que un agente le pasaría a arca_emitir_factura:

{
  "ptoVta": 1,
  "cbteTipo": 6,
  "docTipo": 99,
  "docNro": 0,
  "condicionIva": 5,
  "items": [{ "neto": 1000, "iva": 5 }]
}

• cbteTipo: 6 = Factura B · docTipo: 99 = Consumidor Final · iva: 5 = 21% · condicionIva: 5 = Consumidor Final.

Respuesta (resumida):

{
  "aprobada": true,
  "cae": "75123456789012",
  "caeVencimiento": "20260704",
  "cbteNro": 151,
  "importes": { "total": 1210, "neto": 1000, "iva": 210, "exento": 0, "noGravado": 0, "tributos": 0 },
  "qrUrl": "https://www.afip.gob.ar/fe/qr/?p=...",
  "entorno": "homologación"
}

Nota sobre condicionIva: desde abril 2026 ARCA exige informar la condición de IVA del receptor. Conviene enviarla siempre. Si se omite, el SDK intenta inferirla del docTipo.

Representación impresa (PDF)

La tool arca_generar_pdf produce el PDF (A4) válido AFIP a partir del comprobante autorizado, replicando el modelo de “Comprobantes en Línea”. Pipeline en src/pdf/: datos → HTML/CSS (nuestro) + QR como SVG inline (generador MIT de Nayuki vendorizado en src/pdf/qrcodegen.ts) → Chrome headless (puppeteer-core) → PDF.

Requisitos y config:

• Chrome/Chromium instalado. Se autodetecta; o definí ARCA_CHROME_PATH con la ruta al ejecutable.
• Perfil del emisor (datos que no vienen de WSFE: razón social, domicilio, condición IVA, IIBB, inicio de actividades): archivo JSON en secrets/emisor.json (ver emisor.example.json) o ruta vía ARCA_EMISOR_FILE. También se puede pasar emisor en la llamada.
• Salida: guarda el PDF en ARCA_PDF_DIR (default ./comprobantes/) con nombre {cuit}_{cod}_{ptovta}_{nro}.pdf y devuelve la ruta. Default: 1 copia (ORIGINAL); configurable con copias.
• El detalle de presentación (ítems con descripción/cantidad/precio, datos del receptor, leyenda, condición de venta) lo provee el agente, ya que WSFE solo maneja importes.

Notas técnicas

• Conexión directa a ARCA: endpoints oficiales wswhomo.afip.gov.ar (homologación) y servicios1.afip.gov.ar (producción). No hay intermediarios.
• WSAA: el token de acceso (TA) se cachea y reutiliza hasta su expiración (TTL configurable), evitando reautenticar en cada llamada.
• Cálculo de importes: el SDK calcula IVA, totales y número de comprobante automáticamente a partir de los ítems.
• Tipos de comprobante / alícuotas IVA más usados: 1=Factura A, 6=Factura B, 11=Factura C; IVA 3=0%, 4=10.5%, 5=21%, 6=27%, 8=5%, 9=2.5%. Consultá arca_parametros para las tablas completas y vigentes.

Licencia

MIT.