Skip to main content
Glama
Auditor DIAN

Auditor DIAN

by RafaGM1108
IMPORTANT

No es un producto oficial de la DIAN, ni está afiliado a ella ni respaldado por ella. "DIAN" solo describe las facturas electrónicas que procesa. Las cifras son un apoyo y requieren revisión de un contador.

Por qué existe

En Colombia se emiten más de 2.300 millones de facturas electrónicas al año, y cada una le llega al comprador como un ZIP con un XML firmado. Para saber cuánto IVA hubo en el bimestre, qué compras son a crédito o qué facturas se anularon, el contador tiene que abrirlas una por una o depender del software contable de cada cliente.

Auditor DIAN lee esos ZIP tal como llegan al correo, guarda cada cliente en su propia base y deja que Claude responda en lenguaje natural. El modelo no calcula nada: cada cifra sale de una consulta SQL sobre los documentos y viene con la lista de CUFE que la respalda, para que puedas verificarla.

Related MCP server: invoice-server

Seguridad y privacidad

Está pensado para manejar información tributaria de terceros. Estas son las garantías y cómo se cumplen:

Garantía

Cómo se cumple

Tus facturas no salen del equipo

Las bases y los archivos se quedan en tu computador. El código no hace llamadas de red, y el lector de XML tiene desactivados la red y las entidades externas (protección contra XXE).

Nada se borra ni se modifica

Las consultas abren la base en solo lectura. Cargar solo agrega, y repetir una carga no duplica nada: cada archivo se reconoce por su SHA-256 y cada documento por su CUFE. Exportar crea un Excel nuevo y nunca sobrescribe uno existente.

La información de un cliente nunca termina en otro

Cuatro filtros independientes, basados en la identificación que trae cada documento: al cargar, al abrir la base, al consultar y al repartir por cliente. Si cargas facturas que no son del cliente, no se guardan y Claude te lo dice (decisión 0011).

Las cifras son exactas y trazables

Montos en decimal exacto, nunca en coma flotante, guardados tal como vienen en el XML. Cada total trae sus CUFE.

Los archivos maliciosos no lo tumban

Tope de tamaño por XML leído con un límite real, no el que declara el ZIP. Un archivo dañado se registra y se salta sin afectar a los demás.

Se puede auditar

Código abierto con licencia MIT, 142 pruebas con 100 % de cobertura exigida en cada cambio, y cada decisión de diseño documentada en docs/decisiones/.

NOTE

Qué ve Claude. Claude no lee tus archivos ni tus bases: solo recibe lo que cada herramienta responde (cifras, CUFE, nombres y NIT de proveedores), y eso se procesa como cualquier otra conversación con Claude. El diagnóstico para soporte no incluye montos ni contenido de facturas.

Para reportar una vulnerabilidad, mira SECURITY.md.

Instalación para contadores

No hace falta saber programar ni contratar un servidor.

  1. Instala Claude Desktop e inicia sesión.

  2. Descarga auditor-dian-<versión>.mcpb de la última versión y ábrelo con doble clic. También puedes instalarlo desde Claude Desktop, en Configuración → Extensiones → Configuración avanzada → Instalar extensión.

  3. Elige la carpeta de datos, donde se guardan las bases de tus clientes. La primera vez, Claude Desktop instala lo necesario en un par de minutos.

  4. Descarga las facturas del correo como siempre y escríbele a Claude: Carga mis facturas.

Claude revisa tu carpeta de Descargas y reparte cada factura al cliente que aparece como comprador. Si encuentra compradores que todavía no tienes registrados, te los muestra con su nombre para que decidas si los creas.

  • Sin rutas: nombra las carpetas como las ves, por ejemplo "la carpeta facturas enero del Escritorio".

  • El NIT como lo escribas: 900.000.009-0, 9000000090 o C.C. 79.123.456. El dígito de verificación se interpreta solo.

  • Repetir es seguro: cargar dos veces lo mismo no duplica nada.

Qué puedes preguntar

Pregunta

Qué responde

¿Cuánto IVA en compras hubo en el bimestre 1 de 2026?

El IVA por tarifa, neto de notas crédito, con sus CUFE

¿Cuánto le compró a cada proveedor en el primer semestre?

Totales por NIT, con notas crédito y de ajuste restadas

¿Qué facturas a crédito llegaron en marzo?

Proveedor, valor y vencimiento

¿Hay facturas repetidas o anuladas?

Posibles duplicados y anulaciones totales o parciales

¿Qué retenciones traen las facturas?

Autorretenciones declaradas por el emisor, por tipo

¿Ya tengo registrada a Mi Cliente SAS? ¿Qué meses tiene cargados?

El historial del cliente: documentos por tipo y por mes, y cada carga

Exporta el informe de IVA a un Excel en mi escritorio

Un .xlsx nuevo con hojas de resumen y detalle

Herramienta

Título

Efecto

listar_clientes

Buscar clientes

Lectura

historial_cliente

Historial del cliente

Lectura

buscar_documentos

Buscar facturas

Lectura

resumen_periodo

Resumen de compras, IVA y retenciones

Lectura

facturas_credito

Facturas a crédito

Lectura

duplicados_y_anulaciones

Facturas repetidas y anuladas

Lectura

diagnostico

Diagnóstico para soporte

Lectura, sin montos

exportar_informe

Exportar informe a Excel

Crea un archivo nuevo

crear_cliente

Registrar cliente

Agrega

ingerir_facturas

Cargar facturas de un cliente

Agrega

ingerir_por_cliente

Cargar facturas y repartir por cliente

Agrega

Ninguna herramienta borra ni modifica datos.

Cómo funciona

flowchart LR
    A["ZIP del correo<br/>AttachedDocument + PDF"] --> B["Lector XML<br/>montos exactos"]
    B -- "solo documentos<br/>del cliente" --> C[("Base local<br/>una por cliente")]
    C --> D["Informes SQL<br/>cada cifra con sus CUFE"]
    D --> E["Servidor MCP<br/>en tu equipo"]
    E <--> F["Claude<br/>responde en español"]

Documentos que lee: factura de venta, factura de exportación, instrumento electrónico de transmisión (tipo 03), notas crédito y débito, documento soporte y nota de ajuste. Para cada uno determina si fue validado por la DIAN, a partir de la respuesta que trae el contenedor.

Informes: compras por proveedor, IVA de compras por bimestre, retenciones, facturas a crédito, duplicados y anulaciones, y documentos sin validar. Todos se exportan a Excel.

Verificado con datos reales. 57 facturas de 20 emisores, de 2020 a 2026, se leen sin errores. Contra el PDF que el propio emisor incluye en el ZIP, 53 coinciden exacto y las 4 restantes se explican: tres porque el PDF redondea y una porque el PDF es una imagen. Las rutas del XML están cotejadas con el Anexo Técnico de Factura Electrónica 1.9 (detalle).

Si algo falla o una cifra no cuadra

Pídele a Claude "dame el diagnóstico de Auditor DIAN" y abre un reporte con los formularios Algo salió mal o Una cifra no cuadra. El diagnóstico trae la versión, los clientes, el número de documentos y las advertencias de lectura, sin montos ni contenido de facturas.

WARNING

No adjuntes facturas reales en un reporte público. Si una cifra no cuadra, di cuál esperabas y de qué documento la sacaste.

Para desarrolladores

Requiere uv y Python 3.11 o superior.

uv sync
uv run pytest            # 142 pruebas
uv run ruff check .

Línea de comandos

uv run auditor clientes crear 900000009 --nombre "Cliente SAS"
uv run auditor ingerir 900000009 ~/facturas/        # ZIP, XML o carpeta
uv run auditor informe 900000009 iva_compras_por_bimestre --desde 2026-01-01 --hasta 2026-02-28 --xlsx iva.xlsx

Las bases viven en ~/.auditor-dian/, o en la carpeta que indique AUDITOR_DIAN_HOME.

En Claude Code, desde la carpeta del repositorio:

claude mcp add auditor -- uv run --directory "$PWD" auditor mcp

En Claude Desktop, en claude_desktop_config.json:

{"mcpServers": {"auditor": {"command": "uv", "args": ["run", "--directory", "/ruta/a/auditor-dian-core", "auditor", "mcp"]}}}

Empaquetar la extensión. ./scripts/empaquetar_mcpb.sh arma dist/auditor-dian-<versión>.mcpb y requiere uv y npx.

Modo desarrollo. Con --desarrollo, el script arma "Auditor DIAN (desarrollo)", que ejecuta el código en modo editable desde el repositorio: tras cada cambio basta con desactivar y volver a activar la extensión. Solo funciona en la máquina donde se armó.

Un paquete aparte puede agregar informes, herramientas MCP o lectores de documentos. Lo declara en su pyproject.toml:

[project.entry-points."auditor_dian.plugins"]
mi_plugin = "mi_paquete:register"

register(app) recibe la interfaz de plugins.py, con un ejemplo completo en tests/plugin_ejemplo.py. Un plugin no puede reemplazar nada del núcleo, y uno que falla se reporta y se salta sin afectar lo demás.

Documentación

Licencia

MIT. Puedes usarlo, modificarlo y distribuirlo libremente, sin garantía. Las cifras siempre requieren revisión de un contador.

Available Tools

11 tools
buscar_documentosBuscar facturasA
Read-only

Busca facturas y notas que recibió el cliente, combinando filtros: proveedor, fechas, valor, tipo de documento, CUFE o medio de pago.

Úsela cuando el usuario pida documentos puntuales, por ejemplo:

  • "Muéstrame las facturas de Claro de este año"

  • "¿Qué facturas de más de 5 millones llegaron en marzo?"

  • "Busca la factura con este CUFE" / "¿Cuáles pagué con tarjeta de crédito?"

No la use para totales de IVA, compras o retenciones (use resumen_periodo): aquí no se suma. Devuelve hasta 200 documentos y cuántos coinciden en total; si son más, pida acotar.

Inputs: cliente (required), cufe, tipo, desde, +5 more.

crear_clienteRegistrar clienteA

Registra un cliente nuevo en este equipo para poder cargar y consultar sus facturas.

Úsela cuando el usuario diga, por ejemplo:

  • "Crea el cliente 900.000.009-9, Mi Cliente SAS"

  • "Sí, créalos" después de que ingerir_por_cliente informe compradores sin cliente: use el NIT y el nombre que esa herramienta devolvió.

Si el cliente ya existe no cambia nada y devuelve su historial (creado: false). Si otro cliente tiene el mismo nombre con otro NIT, lo avisa: puede ser un NIT mal escrito y conviene confirmarlo con el usuario.

Inputs: nombre (required), cliente (required).

diagnosticoDiagnóstico para soporteA
Read-only

Estado de la instalación para reportar un problema: versión, carpeta de datos, plugins y, por cliente, documentos, archivos cargados, última carga y advertencias de lectura (las últimas 20). No incluye montos ni contenido de las facturas, así que se puede compartir.

Úsela cuando el usuario diga, por ejemplo:

  • "Algo no funciona" / "No me cargó una factura" / "Una cifra no me cuadra"

  • "Dame el diagnóstico de Auditor DIAN"

Explique en palabras sencillas lo que encuentre y, si hay que reportarlo, entréguele el resultado completo para que lo copie.

Inputs: no named parameters.

duplicados_y_anulacionesFacturas repetidas y anuladasA
Read-only

Facturas del mismo proveedor y número con distinto CUFE (posibles duplicados) y facturas anuladas total o parcialmente por notas crédito (tolerancia de 2 pesos).

Úsela cuando el usuario pregunte, por ejemplo:

  • "¿Hay facturas repetidas?"

  • "¿Qué facturas me anularon con nota crédito?"

  • Antes de cerrar un periodo, para revisar que no se cuente dos veces una compra.

Inputs: desde (required), hasta (required), cliente (required).

exportar_informeExportar informe a ExcelA

Guarda un informe del periodo en un Excel nuevo, con una hoja de resumen y otra de detalle con los CUFE.

Úsela cuando el usuario pida, por ejemplo:

  • "Exporta las retenciones del primer semestre a Excel"

  • "Pásame a un Excel las compras por proveedor de 2025, en el escritorio"

Nunca sobrescribe: si el archivo ya existe, proponga otro nombre. Devuelve dónde quedó.

Inputs: ruta (required), desde (required), hasta (required), cliente (required), +1 more.

facturas_creditoFacturas a créditoA
Read-only

Facturas recibidas con forma de pago a crédito en el periodo, con proveedor, valor y vencimiento.

Úsela cuando el usuario pregunte, por ejemplo:

  • "¿Qué facturas a crédito llegaron en marzo?"

  • "¿Qué le debo a proveedores?" (solo lo que dicen las facturas, no si ya se pagó)

Los eventos (acuse, aceptación, endoso) quedan "por verificar": este servidor no consulta a la DIAN.

Inputs: desde (required), hasta (required), cliente (required).

historial_clienteHistorial del clienteA
Read-only

Ficha de un cliente registrado: nombre, fecha de registro, cuántos documentos tiene por tipo y por mes de emisión, primera y última fecha de emisión, y cada día en que se cargaron facturas con sus archivos, documentos y errores.

Úsela cuando el usuario pregunte, por ejemplo:

  • "¿Qué tengo cargado de Panadería La Espiga?"

  • "¿Me faltan meses de este cliente?" / "¿Hasta qué fecha tengo facturas?"

  • "¿Cuándo cargué las facturas de marzo?"

No trae montos: para cifras use resumen_periodo.

Inputs: cliente (required).

ingerir_facturasCargar facturas de un clienteA

Carga en un cliente las facturas electrónicas de un ZIP o XML (como llegan por correo) o de una carpeta completa.

Úsela cuando el usuario diga a qué cliente van, por ejemplo:

  • "Carga las facturas de la carpeta 'facturas enero' para Mi Cliente SAS"

Si no dice de qué cliente son, o la carpeta trae facturas de varios clientes, use ingerir_por_cliente. Solo agrega: lo ya cargado se salta y nada se duplica. Devuelve cuántos archivos y documentos entraron y los errores de lectura.

Inputs: ruta (required), cliente (required).

ingerir_por_clienteCargar facturas y repartir por clienteA

Carga facturas de varios clientes a la vez: cada archivo va al cliente que aparece como comprador en la factura.

Úsela cuando el usuario diga, por ejemplo:

  • "Carga mis facturas" / "Ya descargué las facturas, cárgalas" (sin ruta)

  • "Reparte por cliente las facturas de la carpeta 'correo noviembre'"

Solo carga en clientes ya registrados. clientes_no_creados trae el NIT y el nombre de los compradores sin registrar: muéstreselos al usuario, pregunte si los crea (crear_cliente) y vuelva a llamar; lo ya cargado no se duplica. sin_asignar lista archivos que no son facturas legibles o traen varios compradores, con el motivo.

Inputs: ruta.

listar_clientesBuscar clientesA
Read-only

Lista los clientes registrados en este equipo (NIT o cédula y nombre), o busca uno.

Úsela cuando el usuario pregunte, por ejemplo:

  • "¿Ya tengo registrada a Panadería La Espiga?"

  • "¿Qué clientes tengo?"

  • Antes de cualquier consulta en la que el usuario nombre al cliente por su razón social y no por su NIT, para obtener el NIT.

Para ver qué meses tiene cargados un cliente use historial_cliente.

Inputs: buscar.

resumen_periodoResumen de compras, IVA y retencionesA
Read-only

Totales del periodo con los CUFE que los respaldan: compras (total y por tipo de documento), IVA (total y por tarifa) y retenciones por tipo. Las notas crédito y de ajuste restan.

Úsela cuando el usuario pregunte cifras, por ejemplo:

  • "¿Cuánto IVA en compras hubo en el bimestre 1?"

  • "¿Qué retenciones traen las facturas del primer semestre?"

  • "¿Cuánto compró en 2025?"

Es el IVA que figura en los documentos, no una determinación de IVA descontable. Las retenciones de facturas y documentos soporte son autorretenciones que declara el emisor (Anexo FE 1.9, FAT01): no diga que se las practicaron al cliente ni que el cliente las practicó. Cite las cifras tal cual vienen, sin sumarlas ni redondearlas.

Inputs: desde (required), hasta (required), cliente (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 11 tools

    Disambiguation4/5

    Descriptions actively cross-reference each other (listar_clientes → historial_cliente → resumen_periodo; ingerir_facturas ↔ ingerir_por_cliente), making boundaries unusually clear. Minor residual overlap: facturas_credito partly duplicates buscar_documentos' payment-method/CUFE filtering, and buscar_documentos vs resumen_periodo could still be confused by an inattentive agent, though both are explicitly disclaimed.

    Naming Consistency3/5

    Half the tools use a verb_noun pattern (listar_clientes, buscar_documentos, crear_cliente, ingerir_facturas, exportar_informe) while the other half are bare nouns (historial_cliente, resumen_periodo, diagnostico, facturas_credito, duplicados_y_anulaciones). All names are readable and domain-meaningful, but the convention is genuinely mixed rather than uniform.

    Tool Count5/5

    Eleven tools for a Colombian e-invoicing audit domain is well within the 3-15 sweet spot, and each maps to a distinct user intent (list, inspect, search, total, diagnose, credit, dedupe, export, create client, ingest two ways). No obvious filler or redundant tool.

    Completeness4/5

    Covers the full read/ingest/export lifecycle including client creation, batch ingestion with unregistered-buyer resolution, period totals, and duplicate/annulment checking. Notable gap: there is no way to delete, re-load, or correct an already-ingested document or client — a real dead end when ingestion goes wrong — and no single-document detail view beyond search results.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Enables Claude to run read-only SQL queries against the DWH.facturas table in SQL Server, including discovering its columns and asking natural-language questions about invoice data.
      2
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to inspect and extract invoice metadata from PDFs, Word documents, Excel files, and images, then synchronize and enrich the extracted data into an Excel ledger.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude to read photos of invoices and create accounts payable entries in the Sienge construction ERP, with supplier lookup, expense classification, duplicate checking, and user confirmation before posting.
      16
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables Claude to open, filter, search, summarize, and write local .xlsx, .xlsm, .xls, and .csv spreadsheets through ten tools, all running locally with no Microsoft Office installed. Access is sandboxed to folders you allow, with an optional read-only mode and an audit log of every file operation.
      10
      MIT