mcp-quipu
Manage a Quipu accounting account via MCP: contacts, invoices, additional income/expenses, and VAT/IRPF summaries.
Contacts: list/search, get, create, update, and delete contacts; capture NIF/CIF needed for invoicing.
Invoices: list by period, get details, create with line items (VAT/IRPF), update, delete (flagged as destructive), and fetch temporary PDF download URLs.
Additional incomes & expenses: list by period, get details, create supplier bills/deductible costs, update, delete, and get PDF download links.
Tax summaries: compute output VAT, input VAT, balance, and withholdings for a quarter or custom date range using
get_tax_summary.Design notes: read-only operations are annotated, writes are limited, and tax arithmetic is done in code rather than by the model.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-quipu ¿Cuánto he facturado este trimestre?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-quipu
MCP server for the Quipu API: invoicing, expenses, contacts, and accounting for freelancers and small businesses in Spain.
It lets an assistant like Claude query and operate your Quipu account in natural language: “How much have I invoiced this quarter?”, “create the September invoice for this client”, “give me the PDF of the latest invoice”.
Built by Nubiia. Sibling of mcp-holded.
Status: alpha (v0.1.0). 18 tools for contacts, invoices, expenses, and tax aggregation. The rest of the API resources are mapped in
docs/api-map.mdbut not yet exposed.
Installation
npm install -g @nubiia/mcp-quipuRelated MCP server: @cynco/mcp
Configuration
You need Quipu API credentials (Settings → API) and your account's slg, which is the first segment of your Quipu URLs: https://getquipu.com/<slg>/…
{
"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"
}
}
}
}Available tools
Contacts
Tool | Description |
| Lists contacts, with filtering by name and pagination |
| Details of a contact |
| Creates a contact (requires |
| Updates only the specified fields |
| Deletes a contact |
Invoices
Tool | Description |
| Lists issued invoices, filterable by period |
| Details of an invoice |
| Issues an invoice with its line items, VAT and IRPF |
| Updates an invoice |
| Deletes an invoice |
| Temporary URL to download the PDF |
Additional expenses and income
Tool | Description |
| Lists expenses and income, filterable by period |
| Details of an entry |
| Records a supplier invoice or deductible expense |
| Updates an entry |
| Deletes an entry |
| Temporary URL of the PDF |
Tax
Tool | Description |
| Output VAT, input VAT, balance, and withholdings for a quarter or range |
Design notes
OAuth2, not API key. Unlike Holded, Quipu issues tokens that expire. The client caches them in memory, renews them with a 60-second margin, and shares a single request across concurrent calls. On a 401, it invalidates the token and retries.
Flattened JSON:API. Quipu returns { data: { id, attributes: {…} }. The tools flatten the response to { id, …attributes}, because models reason much better on flat objects and save wrapper tokens.
Writes are more restricted than reads. An invoice created by error is not a row in a database: it is a document with legal effects. Write operations have stricter quotas, and destructive ones are annotated with destructiveHint.
Tax arithmetic is done in code, not in the model. Quipu does not expose any tax form endpoints (130, 303, 111), so the figures must be derived from invoices and expenses. get_tax_summary walks through all pages of both resources, adds with rounding to cents, and returns the already calculated balance. Asking a model to add up a long list of amounts token by token is a sure-fire way to get a wrong tax figure.
Amounts come as text and with non-obvious names. The base amount is total_amount_without_taxes and the tax is vat_amount — there are no total or subtotal. The adder accepts a comma as a decimal separator, ignores empty values, and on a non-parseable value excludes it and warns in the response instead of propagating a silent NaN.
On deleting invoices. Spanish regulations require correcting by means of a corrective invoice, not by deleting an already numbered invoice. delete_invoice exists because the API allows it, but the tool description warns of this so that the model does not propose it lightly.
Development
npm install
npm run build
npm test
npm run lintRoadmap
plified_invoices— receips and simplified invoices (7 ops)paysheets— payrol (5 ops)numbering_series,accounting_cateories,accounting_subcateoriesatachmentsandbook_entriesAutomatic resolution of the
owner_lugviaGET /users/{id}
License
MIT
Available Tools
18 toolscreate_additional_incomeA
Record an expense or additional income in Quipu. Use it to log supplier bills and deductible costs. Assign an accounting_category_id whenever you know it — an uncategorised expense still counts for VAT but is useless for the profit and loss breakdown.
Inputs: items (required), kind, notes, number, +6 more.
create_contactA
Create a contact in Quipu. name is required. Provide tax_id (NIF/CIF) whenever the contact will be invoiced — Spanish invoices require it and Quipu will reject the invoice later without it.
Inputs: name (required), town, email, phone, +4 more.
create_invoiceA
Create an issued invoice in Quipu. Requires the contact id it is billed to and at least one line item. The contact must already have a tax_id (NIF/CIF) or Quipu will reject the invoice.
Inputs: items (required), contact_id (required), due_date, issue_date, +1 more.
delete_additional_incomeADestructive
Delete an additional income or expense entry from Quipu permanently.
Inputs: id (required).
delete_contactADestructive
Delete a Quipu contact permanently. Quipu refuses to delete contacts that already have invoices attached; in that case the API returns an error explaining it.
Inputs: id (required).
delete_invoiceADestructive
Delete a Quipu invoice permanently. Spanish invoicing rules generally require issuing a credit note instead of deleting a numbered invoice — prefer that unless the invoice is still a draft.
Inputs: id (required).
get_additional_incomeARead-only
Get a single additional income or expense entry from Quipu by its id.
Inputs: id (required).
get_additional_income_download_urlARead-only
Get a temporary public URL to download an expense document as PDF. The link is ephemeral and expires.
Inputs: id (required).
get_contactARead-only
Get a single Quipu contact by its id, with all available attributes (name, tax_id, email, phone, address, town, zip_code, country_code).
Inputs: id (required).
get_invoiceARead-only
Get a single Quipu invoice by id, with all of its attributes and totals.
Inputs: id (required).
get_invoice_download_urlARead-only
Get a temporary public URL to download a Quipu invoice as PDF. The link is ephemeral and expires, so fetch it when the user actually needs the document rather than storing it.
Inputs: id (required).
get_tax_summaryARead-only
Work out the VAT and IRPF position for a period from the invoices and expenses recorded in Quipu. Give it a year and a quarter (or an explicit date range) and it returns output VAT charged on invoices, input VAT paid on expenses, the resulting balance, and withholdings. Use this instead of listing invoices and adding them up by hand: Quipu has no endpoint that returns tax models (130, 303, 111), so the figures must be derived, and doing the arithmetic in code avoids the mistakes that come from adding long lists token by token. Treat the result as an estimate for orientation, not as a filed return.
Inputs: to, from, year, quarter.
list_additional_incomesARead-only
List additional incomes and expenses recorded in Quipu — everything that is not an issued invoice: supplier bills, purchases, tickets and other deductible costs. Returns kind, total_amount_without_taxes, vat_amount and retention_amount. Bound the period with filter_from / filter_to. This is the input-VAT side needed to work out what a quarter actually owes.
Inputs: page, filter_to, filter_from.
list_contactsARead-only
List contacts (clients and suppliers) from Quipu. Returns id, name, tax_id (NIF/CIF), email, phone and address fields. Results are paginated: use page to walk through pages. Quipu returns JSON:API, but this tool flattens each resource so attributes appear at the top level alongside id.
Inputs: page, filter_name.
list_invoicesARead-only
List issued invoices from Quipu, with number, issue_date, due_date, total, subtotal and payment status. Paginated via page. Use filter_from and filter_to to bound the period — this is the tool to use when asked about revenue or VAT for a quarter, since Quipu has no endpoint that returns tax models directly and the figures must be derived from invoices.
Inputs: page, filter_to, filter_from.
update_additional_incomeA
Update an existing additional income or expense in Quipu. Only the fields passed are modified.
Inputs: id (required), notes, number, paid_at, +3 more.
update_contactA
Update an existing Quipu contact. Only the fields you pass are modified; everything else is left untouched.
Inputs: id (required), name, town, email, +5 more.
update_invoiceA
Update an existing Quipu invoice. Note that Spanish invoicing rules restrict what can change once an invoice is issued and numbered; Quipu returns an error when a field is locked.
Inputs: id (required), paid_at, due_date, issue_date, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct resource (contact, invoice, additional income, tax summary) and action (list, get, create, update, delete, download URL). The two download tools are clearly separated by resource type, and the tax summary tool is explicitly positioned as the calculation endpoint rather than a list operation.
Tool names consistently follow a verb_noun pattern: list_*, get_*, create_*, update_*, delete_*. Pluralization is consistent for list operations and singular for single-resource operations, which makes the set predictable.
18 tools is slightly above the ideal 3-15 range but still well-scoped: the count is justified by three resource domains (contacts, invoices, additional incomes) plus a tax summary tool. Each tool has a clear purpose, though the set feels a bit heavy.
CRUD coverage is complete for contacts, invoices, and additional incomes, with download URLs and a tax summary tool as useful additions. The main gap is the lack of a credit-note creation tool despite the delete_invoice description recommending credit notes, and there is no way to list accounting categories referenced by create_additional_income.
Maintenance
Related MCP Connectors
Spanish Veri*factu invoicing: create invoices, expenses and VAT returns from your AI assistant.
Query your books, company data, business health, and ship invoices from your AI assistant.
Your books in your AI assistant: draft expenses, bills, invoices, estimates; ask about P&L, tax.
521Invoicing your AI agent runs for you: invoices, quotes, expenses, VAT books. Veri*factu for Spain.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to query and manage QuickBooks Online data through natural language, including customers, invoices, bills, vendors, accounts, and financial reports.7MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read and write Cynco accounting data, including querying books, creating invoices, reconciling transactions, and generating financial reports.1MIT
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to QuickBooks Online, enabling management of invoices, customers, expenses, and reports through natural language.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with the SuperFaktura invoicing system for managing invoices, clients, and expenses via natural language.4Apache 2.0