holded-mcp

MCP server for invoicing and treasury management in Holded: invoices, purchases, estimates, credit notes, sales receipts, recurring invoices, contacts, bank accounts and cashflow forecasting.

Tools (42)

Sales invoices

Purchases / expenses

Estimates

Credit notes

Simplified receipts

Recurring invoices

Contacts

Treasury

Cashflow

Remittances

Configuration

Related MCP server: MCP Holded

Typical flows

Create and send an invoice to a client

1. list_contacts(search="client name")           → contact_id
2. list_taxes()                                   → tax ids
3. list_numbering_series("invoice")               → number_line_id
4. create_invoice(contact_id, date, items=[{
     name: "Service", units: 1, price: 800,
     taxes: [vat_id, withholding_id]
   }], number_line_id=...)                        → invoice_id
5. approve_invoice(invoice_id)                    → finalizes with definitive number
6. send_invoice(invoice_id, emails=["client@..."])

Collect a pending invoice

1. list_invoices(status="pending", start_date="2026-01-01")
2. register_invoice_payment(invoice_id, amount=..., date="2026-06-17")

Estimate → Invoice

1. create_estimate(contact_id, date, items)       → estimate_id
2. send_invoice(estimate_id, emails=[...])         → send to client
3. convert_estimate_to_invoice(estimate_id)        → once accepted
4. approve_invoice(new_invoice_id)

Setup

1. Get your API key: Holded → Settings → Integrations → API.

2. Install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

MCP client configuration

{
  "mcpServers": {
    "holded": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/holded-mcp/server.py"],
      "env": {
        "HOLDED_API_KEY": "pat_xxxxx..."
      }
    }
  }
}

Confirmation required for critical operations

These tools require confirmed=True. Called without it, they return a JSON with requires_confirmation: true that the calling agent MUST show to the user and wait for a response before repeating the call with confirmed=True. They're financial operations tied to fiscal numbering, or ones that send something to a real recipient — often irreversible once executed.

# 1. First call — no confirmed
approve_invoice(invoice_id="abc123")
# → returns requires_confirmation: true → show it to the user

# 2. Second call — after the user confirms
approve_invoice(invoice_id="abc123", confirmed=True)

Response size

list_invoices/list_purchases/list_estimates/list_credit_notes/list_sales_receipts/list_bank_movements no longer include each document's full line-item array (still available via get_invoice/get_purchase/etc.) — measured 76-81% smaller on real data. Without this, a multi-month list_invoices call could exceed a client's response size limit outright. list_contacts is trimmed to identity fields for the same reason.

Response size (part 2)

get_invoice_pdf used to return the entire PDF as base64 when no save_path was given — measured 68,419 characters for a real invoice. It now saves to ~/Downloads/holded-mcp/ by default and returns just the path (measured: 105 characters, -99.8%), matching the pattern already used elsewhere in this repo family for binary content. Pass as_base64=True for the rare case where you actually need the bytes inline.

Security

• Every tool carries MCP Tool Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) describing its effect up front.

• API failures are raised as exceptions and always surface as real MCP protocol errors (isError=true) — no tool catches a Holded API error and quietly turns it into a JSON payload that looks like a successful response.

Notes and known API quirks

• Auth: PAT tokens (pat_...) use Authorization: Bearer <pat_...>, not a key: value header.

• All POST/PUT bodies use snake_case (contact_id, due_date, number_line_id...) — the v2 API rejects camelCase with a 400.

• No server-side date filtering — the server paginates through the full cursor and filters by date client-side.

• draft is a boolean flag on the document, not a status value. Valid statuses: pending, completed, partial, cancelled, failed, overdue.

• Purchase reconciliation only works from the UI — the public API v2 doesn't support reconciling purchase-type movements (reconcile_bank_movement with document_type: "purchase" always produces a zero-amount forced_reconciled). Use the Holded UI (Expenses → edit payment → select bank account) for that specific case.

• register_invoice_payment/register_purchase_payment use treasury_id internally (the tool accepts account_id and maps it for you); free text goes in description, not notes.

• No delete endpoint exists in the API for invoices, purchases, estimates or credit notes — only the Holded UI can remove a document.

• create_cashflow_forecast requires an approved (non-draft) document — approve first with approve_invoice.

• Attachments use multipart/form-data with no explicit Content-Type header (let requests set it).

License

MIT — see LICENSE.