Skip to main content
Glama
mcp-quipu

mcp-quipu

by nubiia-dev

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.md but not yet exposed.

Installation

npm install -g @nubiia/mcp-quipu

Related 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

list_contacts

Lists contacts, with filtering by name and pagination

get_contact

Details of a contact

create_contact

Creates a contact (requires name; NIF/CIF is required to invoice them)

update_contact

Updates only the specified fields

delete_contact

Deletes a contact

Invoices

Tool

Description

list_invoices

Lists issued invoices, filterable by period

get_invoice

Details of an invoice

create_invoice

Issues an invoice with its line items, VAT and IRPF

update_invoice

Updates an invoice

delete_invoice

Deletes an invoice

get_invoice_download_url

Temporary URL to download the PDF

Additional expenses and income

Tool

Description

list_additional_incomes

Lists expenses and income, filterable by period

get_additional_income

Details of an entry

create_additional_income

Records a supplier invoice or deductible expense

update_additional_income

Updates an entry

delete_additional_income

Deletes an entry

get_additional_income_download_url

Temporary URL of the PDF

Tax

Tool

Description

get_tax_summary

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 lint

Roadmap

  • plified_invoices — receips and simplified invoices (7 ops)

  • paysheets — payrol (5 ops)

  • numbering_series, accounting_cateories, accounting_subcateories

  • atachments and book_entries

  • Automatic resolution of the owner_lug via GET /users/{id}

License

MIT

Available Tools

18 tools
create_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_incomeA
Destructive

Delete an additional income or expense entry from Quipu permanently.

Inputs: id (required).

delete_contactA
Destructive

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_invoiceA
Destructive

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_incomeA
Read-only

Get a single additional income or expense entry from Quipu by its id.

Inputs: id (required).

get_additional_income_download_urlA
Read-only

Get a temporary public URL to download an expense document as PDF. The link is ephemeral and expires.

Inputs: id (required).

get_contactA
Read-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_invoiceA
Read-only

Get a single Quipu invoice by id, with all of its attributes and totals.

Inputs: id (required).

get_invoice_download_urlA
Read-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_summaryA
Read-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_incomesA
Read-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_contactsA
Read-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_invoicesA
Read-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

    A4.1/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query and manage QuickBooks Online data through natural language, including customers, invoices, bills, vendors, accounts, and financial reports.
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to read and write Cynco accounting data, including querying books, creating invoices, reconciling transactions, and generating financial reports.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants to QuickBooks Online, enabling management of invoices, customers, expenses, and reports through natural language.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with the SuperFaktura invoicing system for managing invoices, clients, and expenses via natural language.
      4
      Apache 2.0