mcp-quipu (io.github.nubiia-dev/mcp-quipu) — Model Context Protocol Server

mcp-quipu is a Model Context Protocol (MCP) server that integrates with the Quipu API to support operations for invoicing, expenses, contacts, and accounting for autónomos and small businesses in Spain. It provides 18 MCP tools, intended to let an assistant query and operate a Quipu account in natural language.

🛠️ Key Features

Quipu API integration for facturación, gastos, contactos y contabilidad
18 MCP tools focused on contacts and invoicing (and related accounting tasks)
Spanish VAT reporting is included as part of the toolset

🚀 Use Cases

Ask questions like “cuánto he facturado este trimestre”
Create invoices for a given client and month (e.g., “créame la factura de septiembre”)
Retrieve documents such as “el PDF de la última factura”

⚡ Developer Benefits

Built for the Model Context Protocol (model-context-protocol)
TypeScript ecosystem alignment indicated by the typescript topic
Topics reflect integration and LLM use cases: quipu, invoicing, facturacion, mcp, claude, llm

⚠️ Limitations

Scope is limited to Quipu API capabilities for Spain and the listed categories
Readme excerpt states “18 herramientas sobre contactos, factura,” implying narrower coverage beyond those areas

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

bash

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>/…

json

{
  "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