Auditor DIAN
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Auditor DIAN Registra a Ferretería López con NIT 900123456 y carga sus facturas de Descargas"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
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.
Instala Claude Desktop e inicia sesión.
Descarga
auditor-dian-<versión>.mcpbde 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.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.
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 |
Herramienta | Título | Efecto |
| Buscar clientes | Lectura |
| Historial del cliente | Lectura |
| Buscar facturas | Lectura |
| Resumen de compras, IVA y retenciones | Lectura |
| Facturas a crédito | Lectura |
| Facturas repetidas y anuladas | Lectura |
| Diagnóstico para soporte | Lectura, sin montos |
| Exportar informe a Excel | Crea un archivo nuevo |
| Registrar cliente | Agrega |
| Cargar facturas de un cliente | Agrega |
| 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.
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.xlsxLas 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 mcpEn 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
SPEC.md: alcance y reglas del proyecto.docs/decisiones/: cada decisión de diseño, con sus alternativas descartadas.docs/investigacion/: cifras, normas y herramientas existentes, con fuentes públicas.docs/bitacora.md: qué se hizo y qué se aprendió en cada sesión.
Licencia
MIT. Puedes usarlo, modificarlo y distribuirlo libremente, sin garantía. Las cifras siempre requieren revisión de un contador.
Available Tools
11 toolsbuscar_documentosBuscar facturasARead-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 soporteARead-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 anuladasARead-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éditoARead-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 clienteARead-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 clientesARead-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 retencionesARead-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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Connect Claude to Dutch accounting software: e-Boekhouden invoices, contacts and ledgers.
Claude, connected to your own Oracle EPM. Each person as themselves, every call checked and logged.
Connect Claude or Cursor to books, invoices, bills, payroll, and sealed closes.
Create, send and track invoices from a conversation in Claude, ChatGPT or any MCP client that supports OAuth. Draft an invoice from one sentence or from last month's invoice for the same client, finalize it, email it to your client and send payment reminders for overdue ones. See revenue by month and by client, download PDFs and e-invoices (ZUGFeRD, XRechnung), and export DATEV packages for your tax advisor. Invoices follow the tax rules of 25 countries, including reverse charge and the small-business VAT exemption. New invoices are drafts, and nothing is emailed until you ask. Pay per invoice with no subscription: the first invoice is free.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables 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-
- FlicenseNot gradedqualityCmaintenanceEnables 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.-
- AlicenseAqualityCmaintenanceEnables 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.161MIT
- AlicenseAqualityBmaintenanceEnables 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.10MIT