Cuéntica MCP
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., "@Cuéntica MCP ¿Cuánto dinero tengo en mis cuentas?"
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.
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=Trueen listados para respuestas compactas (menos tokens)
Related MCP server: billy-mcp
Requisitos
Obtener el token de API
Inicia sesión en app.cuentica.com
Ve a Configuración → API → Generar token
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 uvNo 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.jsonWindows:
%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-mcpClaude Code
claude mcp add -s user cuentica -e CUENTICA_API_TOKEN=tu_token -- uvx cuentica-mcpEl 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:
uvxArgs:
cuentica-mcpVariable 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.serverPara 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 |
| Datos del negocio |
| Series de facturación |
Facturas
Herramienta | Descripción |
| Listar con filtros ( |
| Detalle de una factura |
| Crear factura ⚠️ |
| Actualizar factura ⚠️ |
| Eliminar factura ⚠️ |
| Link público |
| Descargar PDF |
| Actualizar cobros ⚠️ |
| Marcar como cobrada (GET+PUT) ⚠️ |
| Enviar por email ⚠️ |
| Anular (Verifactu) ⚠️ |
Gastos
Herramienta | Descripción |
| Listar con filtros ( |
| Detalle de un gasto |
| Crear gasto ⚠️ |
| Actualizar gasto ⚠️ |
| Eliminar gasto ⚠️ |
| Actualizar pagos ⚠️ |
| Marcar como pagado (GET+PUT) ⚠️ |
| Obtener adjunto |
| Actualizar adjunto ⚠️ |
| Eliminar adjunto ⚠️ |
Ingresos
Herramienta | Descripción |
| Listar con filtros ( |
| Detalle de un ingreso |
| Crear ingreso ⚠️ |
| Actualizar ingreso ⚠️ |
| Eliminar ingreso ⚠️ |
| Actualizar cobros ⚠️ |
| Obtener adjunto |
| Actualizar adjunto ⚠️ |
| Eliminar adjunto ⚠️ |
Clientes
Herramienta | Descripción |
| Buscar clientes ( |
| Detalle de un cliente |
| Crear cliente ⚠️ |
| Actualizar cliente ⚠️ |
| Eliminar cliente ⚠️ |
Proveedores
Herramienta | Descripción |
| Buscar proveedores ( |
| Detalle de un proveedor |
| Crear proveedor ⚠️ |
| Actualizar proveedor ⚠️ |
| Eliminar proveedor ⚠️ |
Cuentas bancarias
Herramienta | Descripción |
| Listar cuentas |
| Detalle de una cuenta |
Documentos
Herramienta | Descripción |
| Listar buzón |
| Detalle de un documento |
| Subir documento ⚠️ |
| Asignar a gasto / cambiar fecha ⚠️ |
| Eliminar documento ⚠️ |
| Obtener adjunto en Base64 |
Etiquetas y traspasos
Herramienta | Descripción |
| Etiquetas disponibles |
| Listar traspasos |
| Detalle de un traspaso |
| Crear traspaso ⚠️ |
| Actualizar traspaso ⚠️ |
| 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 |
| Todas las facturas pendientes de cobro (itera páginas auto) |
| Resumen de IVA de un trimestre (repercutido, soportado, neto) |
| 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 |
| Clientes (id, tradename, cif, email) |
| Proveedores (id, tradename, cif, email) |
| Cuentas (id, name, type, balance) |
| 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 toolscreate_customerBDestructive
⚠️ 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_documentADestructive
⚠️ Sube documento al buzón. data en Base64. Confirmar con usuario.
Inputs: filename (required), data (required), date, expense_id. Returns: object
create_expenseADestructive
⚠️ 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_incomeCDestructive
⚠️ 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_invoiceADestructive
⚠️ 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_providerBDestructive
⚠️ 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_transferBDestructive
⚠️ 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_customerADestructive
⚠️ Elimina un cliente (irreversible). Confirmar con usuario.
Inputs: customer_id (required). Returns: object
delete_documentADestructive
⚠️ Elimina un documento (irreversible). Confirmar con usuario.
Inputs: document_id (required). Returns: object
delete_expenseBDestructive
⚠️ Elimina un gasto (irreversible). Confirmar con usuario.
Inputs: expense_id (required). Returns: object
delete_expense_attachmentADestructive
⚠️ Elimina el adjunto de un gasto (irreversible). Confirmar con usuario.
Inputs: expense_id (required). Returns: object
delete_incomeADestructive
⚠️ Elimina un ingreso (irreversible). Confirmar con usuario.
Inputs: income_id (required). Returns: object
delete_income_attachmentADestructive
⚠️ Elimina el adjunto de un ingreso (irreversible). Confirmar con usuario.
Inputs: income_id (required). Returns: object
delete_invoiceADestructive
⚠️ Elimina una factura (irreversible). Confirmar con usuario.
Inputs: invoice_id (required). Returns: object
delete_providerADestructive
⚠️ Elimina un proveedor (irreversible). Confirmar con usuario.
Inputs: provider_id (required). Returns: object
delete_transferADestructive
⚠️ Elimina un traspaso (irreversible). Confirmar con usuario.
Inputs: transfer_id (required). Returns: object
get_accountBRead-onlyIdempotent
Detalle de una cuenta bancaria.
Inputs: account_id (required). Returns: object
get_balance_summaryARead-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_companyARead-onlyIdempotent
Datos del negocio: nombre, CIF, dirección, series de facturación, logo.
Inputs: no named parameters. Returns: object
get_customerCRead-onlyIdempotent
Detalle de un cliente.
Inputs: customer_id (required). Returns: object
get_documentCRead-onlyIdempotent
Detalle de un documento.
Inputs: document_id (required). Returns: object
get_document_attachmentCRead-onlyIdempotent
Contenido del adjunto de un documento en Base64.
Inputs: document_id (required). Returns: object
get_expenseCRead-onlyIdempotent
Detalle completo de un gasto.
Inputs: expense_id (required). Returns: object
get_expense_attachmentBRead-onlyIdempotent
Adjunto de un gasto en Base64 ({filename, data, mimetype}).
Inputs: expense_id (required). Returns: object
get_incomeCRead-onlyIdempotent
Detalle completo de un ingreso.
Inputs: income_id (required). Returns: object
get_income_attachmentBRead-onlyIdempotent
Adjunto de un ingreso en Base64.
Inputs: income_id (required). Returns: object
get_invoiceCRead-onlyIdempotent
Detalle completo de una factura por su ID interno.
Inputs: invoice_id (required). Returns: object
get_invoice_pdfARead-onlyIdempotent
Descarga el PDF de la factura. Devuelve el contenido en Base64.
Inputs: invoice_id (required). Returns: result
get_invoice_public_linkARead-onlyIdempotent
Link público de la factura para compartir con el cliente (incluye botón de pago Stripe).
Inputs: invoice_id (required). Returns: object
get_invoice_seriesCRead-only
Series de facturación configuradas.
Inputs: no named parameters. Returns: result
get_pending_collectionsARead-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_providerCRead-onlyIdempotent
Detalle de un proveedor.
Inputs: provider_id (required). Returns: object
get_quarterly_vat_summaryARead-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_transferBRead-onlyIdempotent
Detalle de un traspaso.
Inputs: transfer_id (required). Returns: object
list_accountsBRead-only
Lista cuentas bancarias, tarjetas y cuentas de socios. type: cash|bank|card|associate.
Inputs: no named parameters. Returns: result
list_customersARead-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_documentsCRead-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_expensesBRead-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_incomeARead-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_invoicesARead-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_providersARead-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_tagsARead-only
Lista todas las etiquetas disponibles.
Inputs: no named parameters. Returns: result
list_transfersARead-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_paidADestructive
⚠️ 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_paidADestructive
⚠️ 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_emailADestructive
⚠️ 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_customerADestructive
⚠️ 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_documentADestructive
⚠️ Actualiza documento: asignar a gasto y/o cambiar fecha. Confirmar con usuario.
Inputs: document_id (required), expense_id, date. Returns: object
update_expenseADestructive
⚠️ 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_attachmentADestructive
⚠️ Actualiza el adjunto de un gasto. data en Base64. Confirmar con usuario.
Inputs: expense_id (required), filename (required), data (required). Returns: object
update_expense_paymentsBDestructive
⚠️ 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_incomeBDestructive
⚠️ 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_attachmentBDestructive
⚠️ Actualiza el adjunto de un ingreso. data en Base64. Confirmar con usuario.
Inputs: income_id (required), filename (required), data (required). Returns: object
update_income_chargesBDestructive
⚠️ Actualiza cobros de un ingreso. charges: [{id?, paid, amount, date, payment_method, destination_account}]
Inputs: income_id (required), charges (required). Returns: object
update_invoiceADestructive
⚠️ 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_chargesADestructive
⚠️ 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_providerCDestructive
⚠️ 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_transferADestructive
⚠️ Actualiza un traspaso. Confirmar con usuario.
Inputs: transfer_id (required), amount (required), concept (required), origin_account (required), +3 more. Returns: object
void_invoiceADestructive
⚠️ 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
Scored across 59 tools
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.
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.
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.
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
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn 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-
- AlicenseBqualityDmaintenanceAn 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.651MIT
- AlicenseAqualityDmaintenanceMCP server that connects Claude Code to the Holded API for natural language financial, accounting, and invoicing queries, with built-in Spanish PGC context.132Apache 2.0
- AlicenseAqualityCmaintenanceMCP 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).234MIT