mcp-quipu

mcp-quipu

Servidor MCP para la API de Quipu: facturación, gastos, contactos y contabilidad para autónomos y pequeñas empresas en España.

Permite que un asistente como Claude consulte y opere tu cuenta de Quipu en lenguaje natural: «¿cuánto he facturado este trimestre?», «créame la factura de septiembre para este cliente», «dame el PDF de la última factura».

Construido por Nubiia. Hermano de mcp-holded.

Estado: estable (v1.0.0). 18 herramientas sobre contactos, facturas, gastos y agregación fiscal. El resto de recursos de la API está mapeado en docs/api-map.md pero aún no expuesto.

Instalación

npm install -g @nubiia/mcp-quipu

Configuración

Necesitas credenciales de API de Quipu (Configuración → API) y el slug de tu cuenta, que es el primer segmento de tus URLs de Quipu: https://getquipu.com/<slug>/…

{
  "mcpServers": {
    "quipu": {
      "command": "npx",
      "args": ["-y", "@nubiia/mcp-quipu"],
      "env": {
        "QUIPU_CLIENT_ID": "tu_client_id",
        "QUIPU_CLIENT_SECRET": "tu_client_secret",
        "QUIPU_OWNER_SLUG": "tu_slug"
      }
    }
  }
}

Herramientas disponibles

Contactos

Herramienta	Descripción
list_contacts	Lista contactos, con filtro por nombre y paginación
get_contact	Detalle de un contacto
create_contact	Crea un contacto (requiere name; el NIF/CIF es obligatorio para facturarle)
update_contact	Actualiza solo los campos indicados
delete_contact	Elimina un contacto

Facturas

Herramienta	Descripción
list_invoices	Lista facturas emitidas, acotables por periodo
get_invoice	Detalle de una factura
create_invoice	Emite una factura con sus líneas, IVA e IRPF
update_invoice	Actualiza una factura
delete_invoice	Elimina una factura
get_invoice_download_url	URL temporal para descargar el PDF

Gastos e ingresos adicionales

Herramienta	Descripción
list_additional_incomes	Lista gastos e ingresos, acotables por periodo
get_additional_income	Detalle de una entrada
create_additional_income	Registra una factura de proveedor o gasto deducible
update_additional_income	Actualiza una entrada
delete_additional_income	Elimina una entrada
get_additional_income_download_url	URL temporal del PDF

Fiscalidad

Herramienta	Descripción
get_tax_summary	IVA repercutido, soportado, saldo y retenciones de un trimestre o rango

Notas de diseño

OAuth2, no API key. A diferencia de Holded, Quipu emite tokens que caducan. El cliente los cachea en memoria, los renueva con un margen de 60 segundos y comparte una sola petición entre llamadas concurrentes. Ante un 401 invalida el token y reintenta.

JSON:API aplanado. Quipu devuelve { data: { id, attributes: {…} } }. Las herramientas aplanan la respuesta a { id, …attributes }, porque los modelos razonan mucho mejor sobre objetos planos y se ahorran tokens de envoltorio.

Las escrituras van más limitadas que las lecturas. Una factura creada por error no es una fila en una base de datos: es un documento con efectos legales. Las operaciones de escritura tienen cupos más estrictos y las destructivas están anotadas con destructiveHint.

La aritmética fiscal se hace en código, no en el modelo. Quipu no expone ningún endpoint de modelos fiscales (130, 303, 111), así que las cifras hay que derivarlas de facturas y gastos. get_tax_summary recorre todas las páginas de ambos recursos, suma con redondeo a céntimos y devuelve el saldo ya calculado. Pedirle a un modelo que sume una lista larga de importes token a token es una forma fiable de obtener una cifra fiscal equivocada.

Los importes vienen como texto y con nombres poco obvios. El importe base es total_amount_without_taxes y el impuesto es vat_amount — no existen total ni subtotal. El sumador acepta coma decimal, ignora vacíos y, ante un valor no parseable, lo excluye y avisa en la respuesta en lugar de propagar un NaN silencioso.

Sobre eliminar facturas. La normativa española exige rectificar mediante factura rectificativa, no borrando una factura ya numerada. delete_invoice existe porque la API lo permite, pero la descripción de la herramienta advierte de ello para que el modelo no lo proponga a la ligera.

Desarrollo

npm install
npm run build
npm test
npm run lint

Roadmap

• simplified_invoices — tickets y facturas simplificadas (7 ops)
• paysheets — nóminas (5 ops)
• numbering_series, accounting_categories, accounting_subcategories
• attachments y book_entries
• Resolución automática del owner_slug vía GET /users/{id}

Licencia

MIT