Cuéntica MCP

MCP server para acceder a la API de Cuéntica desde Claude, Cursor, Windsurf u cualquier cliente compatible con el protocolo MCP.

Desarrollado por UNGRYNERD.

Qué puedes hacer

• 📄 Listar, crear, actualizar y eliminar facturas y borradores
• 💰 Consultar facturas pendientes de cobro con get_pending_collections (paginación automática)
• ✅ Marcar facturas y gastos como cobrados/pagados en una sola llamada (mark_invoice_paid, mark_expense_paid)
• 📧 Enviar facturas por email al cliente
• 🧾 Crear, consultar y gestionar gastos e ingresos
• 👥 Gestión completa de clientes y proveedores (CRUD)
• 🏦 Ver saldo total de todas las cuentas con get_balance_summary
• 📊 Resumen de IVA trimestral con get_quarterly_vat_summary (repercutido, soportado, neto)
• 📁 Gestionar documentos del buzón de Cuéntica
• 🏷️ Gestionar etiquetas y traspasos
• 🗂️ Catálogos ligeros vía MCP Resources (clientes, proveedores, cuentas, etiquetas)
• ⚡ Modo summary=True en listados para respuestas compactas (menos tokens)

Requisitos

• Python 3.10 o superior
• uv (recomendado) o pip
• Cuenta activa en Cuéntica con acceso a la API

Obtener el token de API

1. Inicia sesión en app.cuentica.com
2. Ve a Configuración → API → Generar token
3. Copia el token — lo necesitarás en la configuración

Requisito previo: instalar uv

Este paquete se ejecuta con uv, la herramienta estándar para MCPs en Python. Si no lo tienes:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS con Homebrew
brew install uv

No hace falta instalar Python ni crear entornos virtuales — uv lo gestiona todo automáticamente.

Instalación

Claude Desktop

Edita tu archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cuentica": {
      "command": "uvx",
      "args": ["cuentica-mcp"],
      "env": {
        "CUENTICA_API_TOKEN": "tu_token_aquí"
      }
    }
  }
}

uvx descarga e instala el paquete automáticamente la primera vez. No necesitas clonar el repositorio ni instalar nada más.

Reinicia Claude Desktop tras editar el archivo. Para actualizar a una nueva versión:

uvx --reinstall cuentica-mcp

Claude Code

claude mcp add -s user cuentica -e CUENTICA_API_TOKEN=tu_token -- uvx cuentica-mcp

El flag -s user lo añade globalmente, disponible en todos tus proyectos.

Cursor / Windsurf / otros clientes MCP

Consulta la documentación de tu cliente para añadir un MCP server con:

• Comando: uvx
• Args: cuentica-mcp
• Variable de entorno: CUENTICA_API_TOKEN=tu_token

Desarrollo local

Si quieres modificar el código:

git clone https://github.com/dacmail/cuentica-mcp
cd cuentica-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
CUENTICA_API_TOKEN=tu_token python -m cuentica_mcp.server

Para usarlo en Claude Desktop apuntando a tu copia local:

"args": ["--from", "/ruta/a/cuentica-mcp", "cuentica-mcp"]

Ejemplos de uso

Una vez configurado, habla con el LLM en lenguaje natural:

"¿Qué facturas tengo pendientes de cobro?"
"Muéstrame los gastos del primer trimestre de 2026"
"¿Cuánto he facturado a este cliente en lo que va de año?"
"Marca la factura 30/2026 como cobrada"
"Envíale la factura 28/2026 por email a [email protected]"
"¿Qué borradores tengo para emitir este mes?"
"Resumen de IVA del primer trimestre"
"¿Cuánto dinero tengo en mis cuentas?"
"Crea una factura de 1.000 € + IVA para el cliente X"
"Dame un listado resumido de todos los gastos de enero"

Herramientas disponibles

Empresa

Facturas

Gastos

Ingresos

Clientes

Proveedores

Cuentas bancarias

Documentos

Etiquetas y traspasos

Agregaciones (nuevas en v0.3.0)

Herramientas que orquestan varias llamadas a la API en una sola operación, reduciendo el consumo de tokens y el número de pasos necesarios.

MCP Resources — catálogos ligeros

Los resources son catálogos que el cliente MCP puede leer bajo demanda, sin consumir tokens del chat. Útiles para conocer los IDs de clientes, proveedores y cuentas antes de crear facturas o gastos.

⚠️ Las herramientas marcadas crean, modifican o eliminan datos. El LLM pedirá confirmación explícita antes de ejecutarlas.

Comportamiento inteligente

El servidor está configurado para:

• Excluir facturas anuladas automáticamente de totales y pendientes (status_description == "voided")
• Filtrar borradores futuros: los borradores con fecha en años futuros son facturas recurrentes preprogramadas, no pendientes reales
• Paginar correctamente: en consultas de "pendientes", itera todas las páginas automáticamente
• Limitar el tamaño de página a un máximo de 50 resultados para no saturar el contexto
• Proteger el token: nunca lo mostrará completo en una respuesta

Limitaciones

• La API de Cuéntica tiene un límite de 600 peticiones cada 5 minutos
• La API es Swagger 2.0 — los tipos de datos siguen ese esquema

Licencia

MIT — úsalo, modifícalo y compártelo libremente.

Contribuir

Pull requests bienvenidos. Si encuentras un endpoint útil que falta o un bug, abre un issue.