Quipu MCP server

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

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

Facturas

Gastos e ingresos adicionales

Fiscalidad

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. gettaxsummary 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.

Shortened. The full README is on GitHub.