{"id":"97d3ba7a-f9c3-4ad1-97bd-225c68e8e736","slug":"mcp-quipu","kind":"mcp","name":"mcp-quipu","summary":"MCP server for the Quipu API: invoicing, expenses, contacts and Spanish VAT reporting for AI assistants like Claude. Built by Nubiia.","owner":"nubiia-dev","repoUrl":"https://github.com/nubiia-dev/mcp-quipu","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-26T14:29:09.000Z","addedAt":"2026-10-14T05:51:11.095Z","logoUrl":"https://avatars.githubusercontent.com/u/297636077?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":["accounting","ai","anthropic","api","autonomos","claude","contabilidad","facturacion"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":true,"reviewed":false,"syncedAt":"2026-10-27T17:32:22.135Z","sample":false,"url":"https://conduits.dev/tools/mcp-quipu","language":"TypeScript","transports":["stdio"],"install":{"npm":"@nubiia/mcp-quipu"},"requirements":{"env":[{"name":"QUIPU_CLIENT_ID","secret":true,"required":true,"description":"Your Quipu API client ID (Quipu → Configuración → API)"},{"name":"QUIPU_CLIENT_SECRET","secret":true,"required":true,"description":"Your Quipu API client secret (Quipu → Configuración → API)"},{"name":"QUIPU_OWNER_SLUG","secret":false,"required":true,"description":"Your Quipu account slug — the first path segment of your Quipu URLs (https://getquipu.com/<slug>/…)"}],"upstreamMayCharge":false},"tools":null,"readme":"# 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"}