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: QuickBooks Online MCP Server

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

Invoices

Additional expenses and income

Tax

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