{
  "markdown": "# mcp-quipu\n\nServidor MCP para la [API de Quipu](https://quipuapp.github.io/api-v1-docs/): facturación, gastos, contactos y contabilidad para autónomos y pequeñas empresas en España.\n\nPermite 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»*.\n\nConstruido por [Nubiia](https://nubiia.es). Hermano de [`mcp-holded`](https://github.com/nubiia-dev/mcp-holded).\n\n> **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`](docs/api-map.md) pero aún no expuesto.\n\n## Instalación\n\n```bash\nnpm install -g @nubiia/mcp-quipu\n```\n\n## Configuración\n\nNecesitas 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>/…`\n\n```json\n{\n  \"mcpServers\": {\n    \"quipu\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nubiia/mcp-quipu\"],\n      \"env\": {\n        \"QUIPU_CLIENT_ID\": \"tu_client_id\",\n        \"QUIPU_CLIENT_SECRET\": \"tu_client_secret\",\n        \"QUIPU_OWNER_SLUG\": \"tu_slug\"\n      }\n    }\n  }\n}\n```\n\n## Herramientas disponibles\n\n### Contactos\n| Herramienta | Descripción |\n|---|---|\n| `list_contacts` | Lista contactos, con filtro por nombre y paginación |\n| `get_contact` | Detalle de un contacto |\n| `create_contact` | Crea un contacto (requiere `name`; el NIF/CIF es obligatorio para facturarle) |\n| `update_contact` | Actualiza solo los campos indicados |\n| `delete_contact` | Elimina un contacto |\n\n### Facturas\n| Herramienta | Descripción |\n|---|---|\n| `list_invoices` | Lista facturas emitidas, acotables por periodo |\n| `get_invoice` | Detalle de una factura |\n| `create_invoice` | Emite una factura con sus líneas, IVA e IRPF |\n| `update_invoice` | Actualiza una factura |\n| `delete_invoice` | Elimina una factura |\n| `get_invoice_download_url` | URL temporal para descargar el PDF |\n\n### Gastos e ingresos adicionales\n| Herramienta | Descripción |\n|---|---|\n| `list_additional_incomes` | Lista gastos e ingresos, acotables por periodo |\n| `get_additional_income` | Detalle de una entrada |\n| `create_additional_income` | Registra una factura de proveedor o gasto deducible |\n| `update_additional_income` | Actualiza una entrada |\n| `delete_additional_income` | Elimina una entrada |\n| `get_additional_income_download_url` | URL temporal del PDF |\n\n### Fiscalidad\n| Herramienta | Descripción |\n|---|---|\n| `get_tax_summary` | IVA repercutido, soportado, saldo y retenciones de un trimestre o rango |\n\n## Notas de diseño\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\n**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.\n\n## Desarrollo\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run lint\n```\n\n## Roadmap\n\n- [ ] `simplified_invoices` — tickets y facturas simplificadas (7 ops)\n- [ ] `paysheets` — nóminas (5 ops)\n- [ ] `numbering_series`, `accounting_categories`, `accounting_subcategories`\n- [ ] `attachments` y `book_entries`\n- [ ] Resolución automática del `owner_slug` vía `GET /users/{id}`\n\n## Licencia\n\nMIT\n",
  "bytes": 4925,
  "sha": "dca87d6595d7104f03e637bc078564631bab8e2ded2c977cb90e62ca4c605ff3",
  "repo_slug": "nubiia-dev/mcp-quipu",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nubiia_dev_mcp_quipu_d48a1456/readme"
}