Skip to main content
Glama
Cuéntica MCP

Cuéntica MCP

by dacmail

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)


Related MCP server: billy-mcp

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 cliente@empresa.com"
"¿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

Herramienta

Descripción

get_company

Datos del negocio

get_invoice_series

Series de facturación

Facturas

Herramienta

Descripción

list_invoices

Listar con filtros (summary=True disponible)

get_invoice

Detalle de una factura

create_invoice

Crear factura ⚠️

update_invoice

Actualizar factura ⚠️

delete_invoice

Eliminar factura ⚠️

get_invoice_public_link

Link público

get_invoice_pdf

Descargar PDF

update_invoice_charges

Actualizar cobros ⚠️

mark_invoice_paid

Marcar como cobrada (GET+PUT) ⚠️

send_invoice_email

Enviar por email ⚠️

void_invoice

Anular (Verifactu) ⚠️

Gastos

Herramienta

Descripción

list_expenses

Listar con filtros (summary=True disponible)

get_expense

Detalle de un gasto

create_expense

Crear gasto ⚠️

update_expense

Actualizar gasto ⚠️

delete_expense

Eliminar gasto ⚠️

update_expense_payments

Actualizar pagos ⚠️

mark_expense_paid

Marcar como pagado (GET+PUT) ⚠️

get_expense_attachment

Obtener adjunto

update_expense_attachment

Actualizar adjunto ⚠️

delete_expense_attachment

Eliminar adjunto ⚠️

Ingresos

Herramienta

Descripción

list_income

Listar con filtros (summary=True disponible)

get_income

Detalle de un ingreso

create_income

Crear ingreso ⚠️

update_income

Actualizar ingreso ⚠️

delete_income

Eliminar ingreso ⚠️

update_income_charges

Actualizar cobros ⚠️

get_income_attachment

Obtener adjunto

update_income_attachment

Actualizar adjunto ⚠️

delete_income_attachment

Eliminar adjunto ⚠️

Clientes

Herramienta

Descripción

list_customers

Buscar clientes (summary=True disponible)

get_customer

Detalle de un cliente

create_customer

Crear cliente ⚠️

update_customer

Actualizar cliente ⚠️

delete_customer

Eliminar cliente ⚠️

Proveedores

Herramienta

Descripción

list_providers

Buscar proveedores (summary=True disponible)

get_provider

Detalle de un proveedor

create_provider

Crear proveedor ⚠️

update_provider

Actualizar proveedor ⚠️

delete_provider

Eliminar proveedor ⚠️

Cuentas bancarias

Herramienta

Descripción

list_accounts

Listar cuentas

get_account

Detalle de una cuenta

Documentos

Herramienta

Descripción

list_documents

Listar buzón

get_document

Detalle de un documento

create_document

Subir documento ⚠️

update_document

Asignar a gasto / cambiar fecha ⚠️

delete_document

Eliminar documento ⚠️

get_document_attachment

Obtener adjunto en Base64

Etiquetas y traspasos

Herramienta

Descripción

list_tags

Etiquetas disponibles

list_transfers

Listar traspasos

get_transfer

Detalle de un traspaso

create_transfer

Crear traspaso ⚠️

update_transfer

Actualizar traspaso ⚠️

delete_transfer

Eliminar traspaso ⚠️

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.

Herramienta

Descripción

get_pending_collections

Todas las facturas pendientes de cobro (itera páginas auto)

get_quarterly_vat_summary

Resumen de IVA de un trimestre (repercutido, soportado, neto)

get_balance_summary

Saldo total y por cuenta de todas las cuentas bancarias

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.

Resource URI

Contenido

cuentica://catalog/customers

Clientes (id, tradename, cif, email)

cuentica://catalog/providers

Proveedores (id, tradename, cif, email)

cuentica://catalog/accounts

Cuentas (id, name, type, balance)

cuentica://catalog/tags

Etiquetas (id, name)

⚠️ 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.

Available Tools

59 tools
create_customerB
Destructive

⚠️ Crea un cliente. Confirmar con usuario.

business_type: "individual"|"company"|"others" Para individual: name y surname_1 obligatorios. Para company/others: business_name obligatorio. default_invoice_language: "default"|"es"|"eu"|"ca"|"en" tax_id_type: "nif"|"vat_id"|"passport"|"country_document"|"residence_certificate"|"other"|"not_registered"|"unidentified"

Inputs: business_type (required), region (required), address (required), postal_code (required), +17 more. Returns: object

create_documentA
Destructive

⚠️ Sube documento al buzón. data en Base64. Confirmar con usuario.

Inputs: filename (required), data (required), date, expense_id. Returns: object

create_expenseA
Destructive

⚠️ Crea un gasto. Confirmar con usuario.

document_type: "invoice"|"ticket" expense_lines: [{description, base, tax, retention, imputation, expense_type(código contable ej:"621"), investment?, investment_data?}] payments: [{amount, payment_method, paid, origin_account(id), date?, destination_account?}] vat_eu: True si el CIF del proveedor empieza por "EU".

Inputs: date (required), draft (required), provider (required), document_type (required), +6 more. Returns: object

create_incomeC
Destructive

⚠️ Crea un ingreso. Confirmar con usuario.

income_lines: [{concept, amount, tax, retention, imputation, income_type?, tax_regime, tax_subjection_code}] charges: [{amount, payment_method, destination_account(id), paid, date?}] document_type: "other_invoice"|"cash_statement"|"interest_settlement"|"bank_doc"|"contract"|"resolution"|"other_doc"

Inputs: customer (required), income_lines (required), charges (required), date, +4 more. Returns: object

create_invoiceA
Destructive

⚠️ Crea una factura. Confirmar con usuario antes de ejecutar.

invoice_lines: [{quantity, concept, amount, discount, tax, retention, sell_type, tax_regime, tax_subjection_code}] charges: [{amount, payment_method, destination_account(id), paid, date?}] sell_type: "service"|"product"|"supplied_cost" tax: 0,4,10,12,21 (IVA) o 0,3,7,9.5,13.5,20 (IGIC) tax_regime: "01"|"02"|"08"|"11"|"17"|"18"|"20" tax_subjection_code: "S1"–"S2"|"N1"–"N2"|"E1"–"E6" payment_method: "cash"|"receipt"|"wire_transfer"|"card"|"promissory_note"|"other"

Inputs: issued (required), invoice_lines (required), charges (required), customer, +10 more. Returns: object

create_providerB
Destructive

⚠️ Crea un proveedor. Confirmar con usuario. default_expense_type: código contable ej "600","621","629". Ver Swagger para lista completa. Ver create_customer para business_type, tax_id_type y demás valores válidos.

Inputs: business_type (required), region (required), address (required), postal_code (required), +17 more. Returns: object

create_transferB
Destructive

⚠️ Crea traspaso entre cuentas. payment_method: cash|wire_transfer|promissory_note. Confirmar con usuario.

Inputs: amount (required), concept (required), origin_account (required), destination_account (required), +2 more. Returns: object

delete_customerA
Destructive

⚠️ Elimina un cliente (irreversible). Confirmar con usuario.

Inputs: customer_id (required). Returns: object

delete_documentA
Destructive

⚠️ Elimina un documento (irreversible). Confirmar con usuario.

Inputs: document_id (required). Returns: object

delete_expenseB
Destructive

⚠️ Elimina un gasto (irreversible). Confirmar con usuario.

Inputs: expense_id (required). Returns: object

delete_expense_attachmentA
Destructive

⚠️ Elimina el adjunto de un gasto (irreversible). Confirmar con usuario.

Inputs: expense_id (required). Returns: object

delete_incomeA
Destructive

⚠️ Elimina un ingreso (irreversible). Confirmar con usuario.

Inputs: income_id (required). Returns: object

delete_income_attachmentA
Destructive

⚠️ Elimina el adjunto de un ingreso (irreversible). Confirmar con usuario.

Inputs: income_id (required). Returns: object

delete_invoiceA
Destructive

⚠️ Elimina una factura (irreversible). Confirmar con usuario.

Inputs: invoice_id (required). Returns: object

delete_providerA
Destructive

⚠️ Elimina un proveedor (irreversible). Confirmar con usuario.

Inputs: provider_id (required). Returns: object

delete_transferA
Destructive

⚠️ Elimina un traspaso (irreversible). Confirmar con usuario.

Inputs: transfer_id (required). Returns: object

get_accountB
Read-onlyIdempotent

Detalle de una cuenta bancaria.

Inputs: account_id (required). Returns: object

get_balance_summaryA
Read-only

Resumen de saldos de todas las cuentas bancarias, tarjetas y efectivo. Una sola llamada. Devuelve: {total_balance, accounts: [{id, name, type, balance}]}

Inputs: no named parameters. Returns: object

get_companyA
Read-onlyIdempotent

Datos del negocio: nombre, CIF, dirección, series de facturación, logo.

Inputs: no named parameters. Returns: object

get_customerC
Read-onlyIdempotent

Detalle de un cliente.

Inputs: customer_id (required). Returns: object

get_documentC
Read-onlyIdempotent

Detalle de un documento.

Inputs: document_id (required). Returns: object

get_document_attachmentC
Read-onlyIdempotent

Contenido del adjunto de un documento en Base64.

Inputs: document_id (required). Returns: object

get_expenseC
Read-onlyIdempotent

Detalle completo de un gasto.

Inputs: expense_id (required). Returns: object

get_expense_attachmentB
Read-onlyIdempotent

Adjunto de un gasto en Base64 ({filename, data, mimetype}).

Inputs: expense_id (required). Returns: object

get_incomeC
Read-onlyIdempotent

Detalle completo de un ingreso.

Inputs: income_id (required). Returns: object

get_income_attachmentB
Read-onlyIdempotent

Adjunto de un ingreso en Base64.

Inputs: income_id (required). Returns: object

get_invoiceC
Read-onlyIdempotent

Detalle completo de una factura por su ID interno.

Inputs: invoice_id (required). Returns: object

get_invoice_pdfA
Read-onlyIdempotent

Descarga el PDF de la factura. Devuelve el contenido en Base64.

Inputs: invoice_id (required). Returns: result

get_invoice_seriesC
Read-only

Series de facturación configuradas.

Inputs: no named parameters. Returns: result

get_pending_collectionsA
Read-only

Resumen de facturas emitidas pendientes de cobro. Itera todas las páginas automáticamente. Excluye facturas anuladas (voided) y ya cobradas (paid=True). year: filtra por año (ej: 2026). Sin year devuelve todos los pendientes. Devuelve: {count, total_pending, invoices: [{id, number, date, customer, total, status}]}

Inputs: year. Returns: object

get_providerC
Read-onlyIdempotent

Detalle de un proveedor.

Inputs: provider_id (required). Returns: object

get_quarterly_vat_summaryA
Read-only

Resumen de IVA de un trimestre (quarter: 1-4). Una sola llamada en vez de iterar manualmente. Agrega todas las facturas emitidas y gastos del período, calcula IVA repercutido y soportado. Devuelve: {period, invoices: {count, taxable_base, vat_charged, retention}, expenses: {count, taxable_base, vat_deductible}, result: {net_vat_payable}}

Inputs: year (required), quarter (required). Returns: object

get_transferB
Read-onlyIdempotent

Detalle de un traspaso.

Inputs: transfer_id (required). Returns: object

list_accountsB
Read-only

Lista cuentas bancarias, tarjetas y cuentas de socios. type: cash|bank|card|associate.

Inputs: no named parameters. Returns: result

list_customersA
Read-only

Lista clientes. q busca en razón social, dirección, CIF, teléfono o email. summary=True devuelve solo id, tradename, cif, email (menos tokens).

Inputs: q, page, page_size, summary. Returns: result

list_documentsC
Read-only

Lista documentos del buzón. assigned=False pendientes de asignar a gasto. extension ej: '!pdf,jpg'.

Inputs: initial_date, end_date, keyword, assigned, +5 more. Returns: result

list_expensesB
Read-only

Lista gastos. draft=True borradores, False confirmados. sort ej: 'date:desc'. summary=True devuelve solo id, date, provider, total, draft, document_number (menos tokens).

Inputs: initial_date, end_date, provider, expense_type, +9 more. Returns: result

list_incomeA
Read-only

Lista ingresos (no facturas). sort ej: 'date:desc'. summary=True devuelve solo id, date, customer, total, document_number (menos tokens).

Inputs: initial_date, end_date, customer, tags, +6 more. Returns: result

list_invoicesA
Read-only

Lista facturas. issued=True emitidas, False borradores. sort ej: 'date:desc'. Fechas yyyy-MM-dd. Para borradores (issued=False) sin fechas especificadas se aplica automáticamente el año en curso. summary=True devuelve solo id, number, date, customer, total, status, paid (menos tokens).

Inputs: issued, initial_date, end_date, customer, +9 more. Returns: result

list_providersA
Read-only

Lista proveedores. q busca en razón social, dirección, CIF, teléfono o email. summary=True devuelve solo id, tradename, cif, email (menos tokens).

Inputs: q, page, page_size, summary. Returns: result

list_tagsA
Read-only

Lista todas las etiquetas disponibles.

Inputs: no named parameters. Returns: result

list_transfersA
Read-only

Lista traspasos entre cuentas. payment_method: cash|wire_transfer|promissory_note.

Inputs: origin_account, destination_account, initial_date, end_date, +6 more. Returns: result

mark_expense_paidA
Destructive

⚠️ Marca todos los pagos de un gasto como pagados. Más rápido que update_expense_payments. Obtiene el gasto automáticamente, marca todos los pagos como paid=True y actualiza. payment_date en formato yyyy-MM-dd. Confirmar con usuario.

Inputs: expense_id (required), payment_date (required), payment_method. Returns: object

mark_invoice_paidA
Destructive

⚠️ Marca todos los cobros de una factura como cobrados. Más rápido que update_invoice_charges. Obtiene la factura automáticamente, marca todos los cobros como paid=True y actualiza. payment_date en formato yyyy-MM-dd. Confirmar con usuario.

Inputs: invoice_id (required), payment_date (required), payment_method. Returns: object

send_invoice_emailA
Destructive

⚠️ Envía la factura por email. Confirmar con usuario antes de ejecutar.

Inputs: invoice_id (required), to (required), reply_to (required), subject (required), +5 more. Returns: object

update_customerA
Destructive

⚠️ Actualiza un cliente. Confirmar con usuario. Ver create_customer para valores válidos.

Inputs: customer_id (required), business_type (required), region (required), address (required), +18 more. Returns: object

update_documentA
Destructive

⚠️ Actualiza documento: asignar a gasto y/o cambiar fecha. Confirmar con usuario.

Inputs: document_id (required), expense_id, date. Returns: object

update_expenseA
Destructive

⚠️ Actualiza gasto. Confirmar con usuario. Líneas/pagos: con id=actualiza, sin id=crea, omitidos=eliminados.

Inputs: expense_id (required), date (required), draft (required), provider (required), +7 more. Returns: object

update_expense_attachmentA
Destructive

⚠️ Actualiza el adjunto de un gasto. data en Base64. Confirmar con usuario.

Inputs: expense_id (required), filename (required), data (required). Returns: object

update_expense_paymentsB
Destructive

⚠️ Actualiza pagos de un gasto (ej: marcarlo como pagado). payments: [{id?, amount, payment_method, paid, origin_account, date?}]

Inputs: expense_id (required), payments (required). Returns: object

update_incomeB
Destructive

⚠️ Actualiza ingreso. Confirmar con usuario. Líneas/cobros: con id=actualiza, sin id=crea, omitidos=eliminados.

Inputs: income_id (required), customer (required), income_lines (required), charges (required), +5 more. Returns: object

update_income_attachmentB
Destructive

⚠️ Actualiza el adjunto de un ingreso. data en Base64. Confirmar con usuario.

Inputs: income_id (required), filename (required), data (required). Returns: object

update_income_chargesB
Destructive

⚠️ Actualiza cobros de un ingreso. charges: [{id?, paid, amount, date, payment_method, destination_account}]

Inputs: income_id (required), charges (required). Returns: object

update_invoiceA
Destructive

⚠️ Actualiza factura. Confirmar con usuario. Líneas/cobros con id=actualiza, sin id=crea, omitidos=se eliminan. Ver create_invoice para estructura de invoice_lines y charges.

Inputs: invoice_id (required), issued (required), customer (required), invoice_lines (required), +9 more. Returns: object

update_invoice_chargesA
Destructive

⚠️ Actualiza cobros de una factura (ej: marcarla como cobrada). Confirmar con usuario. charges: [{id?, paid, amount, date, payment_method, destination_account}] Con id=actualiza, sin id=crea, omitidos=eliminados.

Inputs: invoice_id (required), charges (required). Returns: object

update_providerC
Destructive

⚠️ Actualiza un proveedor. Confirmar con usuario. Ver create_provider para valores válidos.

Inputs: provider_id (required), business_type (required), region (required), address (required), +18 more. Returns: object

update_transferA
Destructive

⚠️ Actualiza un traspaso. Confirmar con usuario.

Inputs: transfer_id (required), amount (required), concept (required), origin_account (required), +3 more. Returns: object

void_invoiceA
Destructive

⚠️ Anula factura Verifactu (irreversible). Solo facturas Verifactu. Confirmar con usuario.

Inputs: invoice_id (required). Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 59 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action (e.g., customers, invoices, expenses, transfers). Despite the large number, the purpose of each tool is clearly defined and separate, minimizing confusion for an agent.

    Naming Consistency4/5

    Tools follow a consistent verb_noun pattern (e.g., create_customer, list_customers). The only minor inconsistency is singular vs. plural nouns (get_customer vs. list_customers), but overall the naming is predictable and systematic.

    Tool Count2/5

    59 tools is excessive for typical MCP server scope. While the domain (accounting) requires many operations, this number likely overwhelms agent decision-making. The tool set could be consolidated or split into multiple servers.

    Completeness4/5

    The server covers full CRUD for major entities (customers, providers, invoices, expenses, income) plus advanced operations (VAT summaries, pending collections, email sending, voiding). Minor gaps exist (e.g., no delete_tag or create_account), but the surface is largely complete for accounting workflows.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that integrates with the FacturaScripts ERP system, providing resources and tools to manage clients, products, invoices, accounting entries, and business analytics through natural language.
      10
      -
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server for Danish accounting via Billy.dk API, enabling natural-language control over invoices, bank lines, reports, and more, with a write-guard for safety.
      65
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that connects Claude Code to the Holded API for natural language financial, accounting, and invoicing queries, with built-in Spanish PGC context.
      13
      2
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Spanish accounting for freelancers and SMEs, enabling AI agents to issue invoices, OCR expense PDFs, reconcile bank transactions, and prepare quarterly VAT (Modelo 303).
      23
      4
      MIT