MCP Holded
This MCP server connects AI assistants to the Holded business management platform, enabling full control over invoicing, contacts, products, accounting, and more through 76+ tools.
📄 Documents – List, create, update, and delete documents (invoices, estimates, credit notes, purchase orders, etc.); pay, email, and PDF documents; ship items; attach files; update tracking info and pipeline stages.
👥 Contacts – List, create, update, and delete contacts (clients, suppliers, leads, etc.); manage contact persons and attachments.
📦 Products – List, create, update, and delete products; manage product images; update stock quantities per warehouse.
🏦 Treasuries – List, create, and retrieve treasury accounts.
💸 Expenses Accounts – List, create, get, update, and delete expense account categories.
🔢 Numbering Series – Get, create, update, and delete document numbering series per document type.
🛒 Sales Channels – List, create, get, update, and delete sales channels.
🏭 Warehouses – List, create, get, update, and delete warehouses; view stock levels per warehouse.
💳 Payments – List, create, get, update, and delete payment methods.
🧾 Taxes – Retrieve all available taxes.
👫 Contact Groups – List, create, get, update, and delete contact groups.
📬 Remittances – List all remittances or retrieve a specific one by ID.
🛠️ Services – List, create, get, update, and delete services.
⏱️ Time Tracking (read-only) – List time-tracking entries across all projects or for a specific project.
📊 Accounting (read-only) – Retrieve the chart of accounts and the daily ledger.
🏧 Banking (experimental) – Reconcile bank-feed transactions against accounting entries (requires HOLDED_ENABLE_EXPERIMENTAL_BANKING=true).
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 Holded List my unpaid invoices"
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 Holded
A Model Context Protocol (MCP) server for the Holded API. This server lets AI assistants like Claude interact with Holded's invoicing, accounting, contacts, products, treasury, HR, time tracking and more.
Built and maintained by Nubiia — automatización e integraciones con IA para negocios (MCP, Holded, Pipedrive y más). ¿Quieres algo así para tu empresa? Escríbenos en nubiia.es.
Features
This MCP server provides access to the Holded API v2 across all supported modules:
Documents (16 tools): Create, list, update, delete invoices, estimates, credit notes, etc. Also pay, send, get PDF, ship items, and more.
Contacts (7 tools): Manage clients and suppliers with attachments.
Products (9 tools): Full product management including images and stock.
Treasuries (3 tools): Manage legacy treasury accounts.
Treasury v2 (15 tools): Bank accounts, bank movements, cash movements, invoicing forecasts and reconciliation.
Expenses Accounts (5 tools): Handle expense account categories.
Numbering Series (4 tools): Configure document numbering.
Sales Channels (5 tools): Manage sales channels.
Warehouses (6 tools): Warehouse management.
Payments (5 tools): Payment method configuration.
Taxes (1 tool): Get available taxes.
Contact Groups (5 tools): Organize contacts into groups.
Remittances (2 tools): Access remittance data.
Services (5 tools): Manage services.
Time Tracking (3 tools): List time-tracking entries and project times (read and write).
Accounting (2 tools, read-only): Get the chart of accounts and the daily ledger.
Ledger (4 tools): List and create accounting/ledger entries.
Team/HR (22 tools): Employee management, payroll records, employee time entries and clock in/out.
Total: 119 tools — all registered unconditionally once a valid v2 key is configured.
Related MCP server: invoiceninja-mcp
Installation
Prerequisites
Node.js 22.14 or higher
A Holded account with API access
A Holded API v2 key (
pat_…orsk_live_…) — generate it in Holded → Settings → API
Install from npm
npm install -g @nubiia/mcp-holdedInstall from source
git clone https://github.com/nubiia-dev/mcp-holded.git
cd mcp-holded
npm install
npm run buildConfiguration
Environment Variables
All tools call the Holded API v2 (Bearer auth, cursor pagination). You need a single v2 key:
# Recommended — primary key name
export HOLDED_API_KEY=pat_your_v2_key_here
# Alternative — accepted as an alias; wins over HOLDED_API_KEY if both are set
export HOLDED_API_KEY_V2=sk_live_your_v2_key_hereGenerate the key in Holded → Settings → API. The key must start with pat_ or sk_live_. A 403 response means the key is missing a required scope.
For multi-tenant setups use the same logic per tenant:
export TENANT_1_NAME=company-a
export TENANT_1_API_KEY=pat_key_for_company_a
export TENANT_2_NAME=company-b
export TENANT_2_API_KEY=sk_live_key_for_company_bTENANT_N_API_KEY_V2 is accepted as an alias for TENANT_N_API_KEY (wins if both are set).
Claude Desktop Configuration
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"holded": {
"command": "npx",
"args": ["-y", "@nubiia/mcp-holded"],
"env": {
"HOLDED_API_KEY": "pat_your_v2_key_here"
}
}
}
}Or if installed from source:
{
"mcpServers": {
"holded": {
"command": "node",
"args": ["/path/to/mcp-holded/dist/index.js"],
"env": {
"HOLDED_API_KEY": "pat_your_v2_key_here"
}
}
}
}Migrating from 1.x
API key
The server now calls the Holded API v2 exclusively. Your 1.x API key (a plain hex string like abc123…) no longer works. Generate a v2 key in Holded → Settings → API; the key will start with pat_ or sk_live_.
Set it as HOLDED_API_KEY (or the alias HOLDED_API_KEY_V2). The separate HOLDED_API_KEY_V2 variable used in 1.x to opt-in to HR/Ledger/Treasury tools is no longer needed — all 119 tools are always registered.
Pagination
List tools changed from page-based to cursor-based pagination:
1.x argument | 2.x argument | Notes |
| (removed) | Server no longer accepts offset pages |
|
| Server-paginated; use limit to control page size |
(none) |
| Pass the |
Responses now follow this envelope:
{
"items": [...],
"nextCursor": "opaque-string-or-null",
"hasMore": true
}Iterate by passing nextCursor as cursor until hasMore is false.
Response format
Field names are
snake_casethroughout (e.g.contact_id,created_at).Monetary amounts are strings with a decimal comma (e.g.
"1.234,56") — parse with your locale-aware number parser before doing arithmetic.
Removed or changed operations
Operation | 1.x behaviour | 2.x behaviour |
| Supported | Removed — create only via |
| All document types | Only |
Ship operations | All document types | Only |
Experimental banking ( | Opt-in via env flag | Removed — use |
| Unix timestamps ( | ISO 8601 strings ( |
| Paginated | Returns all taxes in one call (no pagination args) |
| Optional warehouse |
|
List tools field projections | Reduced default set of fields | Full v2 payload returned; use |
Contact attachments
Attachments are now fetched by filename instead of attachment ID. Use get_contact_attachment with the filename field returned by list_contact_attachments.
Usage Examples
Once configured, you can ask Claude to:
Documents
"List all my invoices from Holded"
"Create an invoice for client X with 2 items"
"Send invoice #123 to the client by email"
"Get the PDF of invoice #456"
"Mark invoice #789 as paid"
Contacts
"List all my clients in Holded"
"Create a new client named Acme Corp"
"Update the email for contact #123"
Products
"Show me all products"
"Create a new product called Widget with price 50 EUR"
"Update stock for product #123 adding 10 units in warehouse W1"
HR & Payroll
"List all employees"
"Clock in employee #456"
"Get the salary record for employee #789 for June 2025"
Reports
"Get all my taxes"
"List all treasury bank accounts"
"Show me the daily ledger for January 2025"
"Get the chart of accounts"
Document Types
The API supports these document types:
Type | Description |
| Sales invoices |
| Sales receipts |
| Credit notes (refunds) |
| Receipt notes |
| Estimates/Quotes |
| Sales orders |
| Packing lists |
| Proforma invoices |
| Purchases |
| Purchase refunds (create only in v2) |
| Purchase orders |
API Reference
Base URL
https://api.holded.com/api/The server routes each tool to the appropriate v2 sub-path (e.g. /invoicing/v2/, /team/v2/, /accounting/v2/).
Authentication
All requests use Bearer authentication with your v2 key:
Authorization: Bearer pat_your_v2_key_herePagination
List endpoints use cursor-based pagination via limit and cursor arguments (see Migrating from 1.x).
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run devWrite Safety
Create/update/delete tools modify real data in Holded. The server applies per-tool rate limits (stricter for destructive operations) to prevent accidental bulk mutations. Destructive operations are capped at 10 requests/minute by default; update operations at 30 requests/minute.
Privacy Policy
Data Collection: This MCP server requires your Holded API key to function. The API key is read from your local environment variable (HOLDED_API_KEY) and is never stored by this server. All API requests and responses are passed through in real-time to facilitate communication between your AI assistant and the Holded API.
Data Usage & Sharing: Your API key and all data processed through this server are used exclusively to interact with the Holded API on your behalf. The server acts as a pass-through proxy - it does not store, log, or retain any data. Your Holded API key and data are transmitted only to Holded's official API endpoints (api.holded.com). No data is shared with any third parties beyond Holded.
Your Security: We recommend following security best practices: store your API key in environment variables (never commit it to version control), regularly update to the latest version, and review the permissions granted to this MCP server in your AI assistant. For more information, see our full Privacy Policy.
Support
For questions, issues, or feature requests:
GitHub Issues: Report an issue
Email: hola@nubiia.es
Documentation: Holded API Docs
About Nubiia
This MCP server is built and maintained by Nubiia.
Nubiia ayuda a empresas a automatizar procesos e integrar sus herramientas con IA: servidores MCP a medida, integraciones con Holded, Pipedrive y otros ERPs/CRMs, y agentes que conectan tus datos de negocio con asistentes como Claude. Este @nubiia/mcp-holded es un ejemplo open source de lo que hacemos.
👉 ¿Quieres una integración o automatización con IA para tu negocio? nubiia.es · ✉️ hola@nubiia.es
License
MIT - See LICENSE file for details.
Author
Built by Nubiia — nubiia.es · hola@nubiia.es
Maintainer: Samuel Fraga — GitHub · LinkedIn
Links
Available Tools
119 toolsarchive_bank_accountA
WRITE: archives a treasury bank account in Holded (API v2). Reversible alternative to delete_bank_account.
Inputs: accountId (required).
attach_file_to_documentA
Attach a file to a document (Holded API v2). POST ${docBase}/{id}/attachments multipart. Supported for all docTypes except purchaserefund (v2 has no purchase-refund CRUD beyond creation).
Inputs: docType (required), filename (required), documentId (required), fileBase64 (required).
clock_in_employeeB
WRITE: registers a clock-in for an employee in Holded time tracking (API v2). Affects real working-time records.
Inputs: employeeId (required).
clock_out_employeeB
WRITE: registers a clock-out for an employee in Holded time tracking (API v2).
Inputs: employeeId (required).
create_accounting_accountB
WRITE: creates a real accounting account in the Holded chart of accounts (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Contabilidad → Crear cuenta).
Inputs: data (required).
create_bank_accountB
WRITE: creates a real treasury bank account in Holded (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Tesorería → Crear cuenta).
Inputs: data (required).
create_bank_movementC
WRITE: creates a real bank movement in a treasury account (Holded API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Tesorería → Crear movimiento).
Inputs: data (required), accountId (required).
create_contactC
Create a new contact (Holded API v2)
Inputs: name (required), code, note, type, +5 more.
create_contact_groupC
Create a new contact group (Holded API v2)
Inputs: name (required).
create_documentA
Create a new document (invoice, estimate, purchase, etc.). By default the document is approved (finalized) so it appears in the Holded UI; pass approveDoc:false to create a draft instead. Set the expense/income account at document level via expAccountId (it cascades to all lines); a per-line account is rejected because Holded ignores it. On SALES documents an auto-incrementing numbering series may OVERRIDE the requested invoiceNum — the tool re-reads the created document and returns a _warnings note if that happened. On purchases the supplier number in invoiceNum is preserved. retention (IRPF) is accepted on sales but rejected on purchases (Holded ignores it there).
Inputs: date (required), items (required), docType (required), contactId (required), +7 more.
create_employeeA
WRITE: creates a real employee record in Holded (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Empleados → Crear) for the payload fields (name, email, etc.).
Inputs: data (required).
create_employee_timeA
WRITE: creates a manual time-tracking record for an employee (Holded API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Control horario → Crear registro).
Inputs: data (required), employeeId (required).
create_expenses_accountC
Create a new expenses account (Holded API v2)
Inputs: name (required), code.
create_invoicing_forecastA
WRITE: creates an invoicing forecast in Holded cashflow (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Tesorería → Previsiones).
Inputs: data (required).
create_ledger_entryA
WRITE: creates a real journal entry in Holded accounting (API v2). Incorrect entries directly distort the company books — double-check accounts and amounts. data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Contabilidad → Crear asiento).
Inputs: data (required).
create_numbering_serieC
Create a new numbering serie (Holded API v2)
Inputs: name (required), docType (required), prefix, nextNumber.
create_paymentC
Create a new payment (Holded API v2)
Inputs: name (required), days.
create_productC
Create a new product (Holded API v2)
Inputs: name (required), sku, tax, kind, +5 more.
create_salary_recordA
WRITE: creates a real payroll record in Holded (API v2) — affects accounting and HR data. Use get_salary_record_defaults first to obtain a valid base payload. data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Registros de nómina → Crear).
Inputs: data (required).
create_sales_channelC
Create a new sales channel (Holded API v2)
Inputs: name (required).
create_serviceC
Create a new service (Holded API v2)
Inputs: name (required), sku, tax, price, +1 more.
create_treasuryC
Create a new treasury account (Holded API v2). Overlaps with list_bank_accounts/get_bank_account/create_bank_account (official treasury tools); consolidation planned for 2.1.
Inputs: name (required), bic, iban, balance.
create_warehouseC
Create a new warehouse (Holded API v2)
Inputs: name (required), city, address, country, +2 more.
delete_bank_accountA
DESTRUCTIVE: permanently deletes a treasury bank account in Holded (API v2). Prefer archive_bank_account to keep history. This cannot be undone.
Inputs: accountId (required).
delete_contactC
Delete a contact (Holded API v2)
Inputs: contactId (required).
delete_contact_groupC
Delete a contact group (Holded API v2)
Inputs: groupId (required).
delete_documentC
Delete a document
Inputs: docType (required), documentId (required).
delete_employeeA
DESTRUCTIVE: permanently deletes an employee record in Holded (API v2). This cannot be undone.
Inputs: employeeId (required).
delete_employee_timeA
DESTRUCTIVE: permanently deletes a time-tracking record in Holded (API v2). This cannot be undone.
Inputs: timeId (required).
delete_expenses_accountC
Delete an expenses account (Holded API v2)
Inputs: accountId (required).
delete_invoicing_forecastA
DESTRUCTIVE: permanently deletes an invoicing forecast in Holded cashflow (API v2).
Inputs: forecastId (required).
delete_numbering_serieC
Delete a numbering serie (Holded API v2)
Inputs: docType (required), serieId (required).
delete_paymentC
Delete a payment (Holded API v2)
Inputs: paymentId (required).
delete_productC
Delete a product (Holded API v2)
Inputs: productId (required).
delete_salary_recordA
DESTRUCTIVE: permanently deletes a payroll record in Holded (API v2). This cannot be undone and affects accounting data.
Inputs: salaryRecordId (required).
delete_sales_channelC
Delete a sales channel (Holded API v2)
Inputs: channelId (required).
delete_serviceC
Delete a service (Holded API v2)
Inputs: serviceId (required).
delete_warehouseC
Delete a warehouse (Holded API v2)
Inputs: warehouseId (required).
get_bank_accountB
Get a treasury bank account by ID (Holded API v2).
Inputs: accountId (required).
get_chart_of_accountsA
Get accounting accounts (Holded API v2, GET /accounting-accounts). Returns every account with num (PGC number, e.g. 40000000), name, group, debit, credit, and balance. Unlike list_expenses_accounts (group-6 only), this includes all groups (assets, liabilities, income, expenses). Cursor-paginated: pass nextCursor from the previous response as cursor. Optional annex filters: archived (include archived accounts), start_date/end_date (ISO 8601, filter by activity period), include_empty (include zero-balance accounts). See also: list_accounting_accounts in ledger tools — both tools target the same v2 endpoint; consolidation is planned for release 2.1. Read-only.
Inputs: limit, cursor, archived, end_date, +2 more.
get_contactB
Get a specific contact by ID (Holded API v2)
Inputs: contactId (required).
get_contact_attachmentA
Get a specific attachment from a contact by filename (Holded API v2). BREAKING CHANGE from v1: the path parameter changed from attachmentId (numeric/UUID) to filename (string). Obtain filenames from list_contact_attachments first.
Inputs: filename (required), contactId (required).
get_contact_groupB
Get a specific contact group by ID (Holded API v2)
Inputs: groupId (required).
get_daily_ledgerA
Get ledger entries / journal (asientos) for a date range (Holded API v2, GET /ledger-entries). Returns one row per ledger line with entryNumber, line, timestamp, type (collect/payment/purchase/…), description, account (PGC num), debit, and credit. This is the authoritative source for balance-sheet and tax-return figures.
Date arguments (at least one form of each bound is required — the v2 API returns 422 without both):
• Primary form : start_date / end_date — ISO 8601 date strings (YYYY-MM-DD)
• Legacy form : starttmp / endtmp — Unix timestamps in seconds; converted automatically to ISO
If both forms are supplied for the same bound, the ISO string takes precedence.
Cursor-paginated: pass nextCursor from a previous response as cursor to retrieve subsequent pages. Large date ranges may require multiple pages. Set groupByEntry to nest lines into full double-entry entries with per-entry debit/credit totals (applied page-scoped).
See also: list_ledger_entries in ledger tools — both tools target the same v2 endpoint. Read-only.
Inputs: limit, cursor, endtmp, end_date, +3 more.
get_documentB
Get a specific document by ID
Inputs: docType (required), documentId (required).
get_document_paymentsA
Get the payments registered against a specific document via the Holded API v2 GET endpoint. Returns { documentId, paymentsDetail } when the v2 response includes a paymentsDetail field; otherwise returns the whole document (v2 field name may differ from v1). Unlike list_payments — which is filtered to the ACTIVE fiscal year — this surfaces payments from ANY year, so use it for cross-year payment audits. Read-only.
Inputs: docType (required), documentId (required).
get_document_pdfA
Get the PDF of a document as base64-encoded binary (Holded API v2). Returns { contentType, base64, bytes, filename }. Supported docTypes: invoice, salesreceipt, creditnote, receiptnote, estimate, proform, salesorder, waybill, purchaseorder. purchase is NOT supported — GET /purchases/{id}/pdf returns 404 for all purchases. purchaserefund has no CRUD support in v2.
Inputs: docType (required), documentId (required).
get_employeeC
Get a single employee by ID (Holded API v2).
Inputs: employeeId (required).
get_employee_contractA
Get the contract details of an employee (Holded API v2). A 404 response means the employee has no contract configured in Holded, not that the employee ID is wrong.
Inputs: employeeId (required).
get_employee_timeB
Get a single time-tracking record by ID (Holded API v2).
Inputs: timeId (required).
get_expenses_accountA
Get a single account by its Holded id (Holded API v2). Despite the "expenses" name, this endpoint serves ANY account (including income/group-7 accounts that list_expenses_accounts omits) when you already know its id.
Inputs: accountId (required).
get_invoicing_forecastB
Get a cashflow invoicing forecast by ID (Holded API v2).
Inputs: forecastId (required).
get_numbering_seriesA
List numbering series for a specific document type (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma.
Inputs: docType (required), limit, cursor, fields, +1 more.
get_paymentA
Get a specific payment by ID (Holded API v2)
Inputs: paymentId (required).
get_productB
Get a specific product by ID (Holded API v2)
Inputs: productId (required).
get_product_main_imageC
Get the main image of a product (Holded API v2)
Inputs: productId (required).
get_product_secondary_imageB
Get a secondary image of a product (Holded API v2)
Inputs: imageId (required), productId (required).
get_project_timeA
Get a single time-tracking entry by project ID and time-tracking ID (Projects API v2). Read-only.
Inputs: projectId (required), timeTrackingId (required).
get_remittanceB
Get a specific remittance by ID (Holded API v2). NOTE: route relocated to /treasury/remittances/{id} in v2.
Inputs: remittanceId (required).
get_salary_recordA
Get a payroll salary record by ID (Holded API v2, scope accounting:payrolls.read). Returns line-by-line earnings and deductions, accounting accounts, totals and payment status.
Inputs: salaryRecordId (required).
get_salary_record_defaultsA
Get the default data for creating a payroll record (Holded API v2). Useful as a base payload for create_salary_record.
Inputs: no named parameters.
get_sales_channelC
Get a specific sales channel by ID (Holded API v2)
Inputs: channelId (required).
get_serviceB
Get a specific service by ID (Holded API v2)
Inputs: serviceId (required).
get_shipped_unitsA
Get shipped/received units for a document (Holded API v2). salesorder → GET /sales-orders/{id}/shipped-items. purchaseorder → GET /purchase-orders/{id}/received-items. All other docTypes are not supported.
Inputs: docType (required), documentId (required).
get_taxesA
Get all available taxes (Holded API v2). The v2 /taxes endpoint returns the complete tax list in one response (no cursor, no pagination). Supports fields to select specific fields and summary to return only the item count. Amounts are strings with decimal comma. Each tax has: key (the stable identifier, e.g. "s_iva_21"/"p_iva_21" — this is the value used in a document line's taxes[]), id (mirrors key), name, amount (the percentage as a string, e.g. "21"), scope ("sales" or "purchase"), group (e.g. "iva"), and type.
Inputs: fields, summary.
get_treasuryA
Get a specific treasury account by ID (Holded API v2). WARNING: the balance field is a STATIC opening figure set on the account, not a live balance computed from transactions — do NOT use it for reconciliation or as the current cash position. Overlaps with list_bank_accounts/get_bank_account/create_bank_account (official treasury tools); consolidation planned for 2.1.
Inputs: treasuryId (required).
get_warehouseA
Get a specific warehouse by ID (Holded API v2)
Inputs: warehouseId (required).
list_accounting_accountsA
List accounting accounts (Holded API v2). Cursor-paginated. For the v1 read-only chart of accounts see get_chart_of_accounts.
Inputs: limit, cursor.
list_bank_accountsB
List treasury bank accounts (Holded API v2, official endpoint). Cursor-paginated.
Inputs: limit, cursor.
list_bank_movementsA
List bank movements of a treasury account (Holded API v2, official endpoint — replaces the experimental internal banking tools). Cursor-paginated.
Inputs: accountId (required), limit, cursor.
list_cash_movementsA
List cash movements of a treasury account (Holded API v2). Cursor-paginated. This endpoint applies to cash-type treasury accounts only; bank and card account types return 404.
Inputs: accountId (required), limit, cursor.
list_contact_attachmentsA
Get list of attachments for a contact (Holded API v2). Use the filenames from the response with get_contact_attachment.
Inputs: contactId (required).
list_contact_groupsB
List contact groups (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma.
Inputs: limit, cursor, fields, summary.
list_contactsA
List contacts (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma.
Inputs: limit, cursor, fields, summary.
list_documentsA
List documents of a specific type (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. NOTE: purchaserefund is not listable in v2 — only creation is supported (POST /purchases/refund).
Inputs: docType (required), limit, cursor, fields, +1 more.
list_employeesA
List employees (Holded API v2, section Equipo y RRHH). Cursor-paginated: pass the previous response nextCursor as cursor to fetch the next page.
Inputs: limit, cursor.
list_employee_timesA
List time-tracking records (Holded API v2). Without employeeId lists all records (/employee-times); with employeeId lists only that employee (/employees/{id}/times). Cursor-paginated.
Inputs: limit, cursor, employeeId.
list_expenses_accountsA
List expenses accounts (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. Each account has id (Holded internal id), name, and accountNum (the PGC account number, e.g. 62900000). NOTE: this endpoint only returns expense/purchase accounts (PGC group 6). Income accounts (group 7, e.g. 700/705/759) are NOT listed here — fetch the full chart via get_chart_of_accounts, or read a known account by id via get_expenses_account.
Inputs: limit, cursor, fields, summary.
list_invoicing_forecastsB
List cashflow invoicing forecasts (Holded API v2). Cursor-paginated.
Inputs: limit, cursor.
list_ledger_entriesA
List journal/ledger entries (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Optionally filter by start_date/end_date (ISO 8601, e.g. 2025-01-01) — the v2 endpoint returns 422 if neither date is provided. For the read-only daily-ledger tool with groupByEntry support and Unix-timestamp backward compat see get_daily_ledger.
Inputs: limit, cursor, end_date, start_date.
list_payment_methodsA
List available payment methods (Holded API v2). GET /payment-methods. Returns an array of {id, name, type, status, isDefault, bankingAccountId} — the v2 {items:[...]} envelope is normalized to a bare array.
Inputs: no named parameters.
list_paymentsA
List all payments (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. NOTE: this endpoint is filtered to the ACTIVE fiscal year, so payments made in a prior year do NOT appear here even if they are linked to documents. For cross-year payment audits, read a document's payments via get_document_payments (the document paymentsDetail). Use start_date/end_date (YYYY-MM-DD) to filter by date — live-verified against v2.
Inputs: limit, cursor, endtmp, fields, +4 more.
list_product_imagesB
List all images of a product (Holded API v2)
Inputs: productId (required).
list_productsA
List products (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Server-paginated; use limit to control page size. Response fields are snake_case; amounts are strings with decimal comma.
Inputs: limit, cursor, fields, summary.
list_project_timesA
List time-tracking entries across all Holded projects (Projects API v2). Returns a cursor-paginated flat list of entries; pass the previous nextCursor as cursor to fetch the next page. Each entry contains timeId, duration (seconds), date (Unix seconds), approved (0/1), projectId, and projectName. The approvedOnly, startDate, and endDate filters are applied client-side on the current page — use pagination to iterate over the full dataset. Read-only.
Inputs: limit, cursor, endDate, startDate, +1 more.
list_project_times_by_projectA
List time-tracking entries for a single Holded project (Projects API v2). Returns a cursor-paginated flat list of entries for the given projectId. Pass the previous nextCursor as cursor to fetch the next page. The approvedOnly, startDate, and endDate filters are applied client-side on the current page. Read-only.
Inputs: projectId (required), limit, cursor, endDate, +2 more.
list_remittancesA
List all remittances (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. NOTE: namespace relocated from /remittances to /treasury/remittances in v2.
Inputs: limit, cursor, fields, summary.
list_salary_recordsA
List payroll salary records (Holded API v2, requires scope accounting:payrolls.read). Each record has employee info, earnings/deductions lines, totals and payment status (PENDING, PAID, PARTIALLY_PAID). Cursor-paginated.
Inputs: limit, cursor.
list_sales_channelsA
List all sales channels (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. Supports field filtering to reduce response size.
Inputs: limit, cursor, fields, summary.
list_servicesA
List all services (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. Supports field filtering to reduce response size.
Inputs: limit, cursor, fields, summary.
list_treasuriesA
List all treasury accounts (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Response fields are snake_case; amounts are strings with decimal comma. WARNING: the balance field is a STATIC opening figure, not a live balance derived from transactions — do NOT rely on it for reconciliation or to compute the current cash position. Overlaps with list_bank_accounts/get_bank_account/create_bank_account (official treasury tools); consolidation planned for 2.1.
Inputs: limit, cursor, fields, summary.
list_warehousesA
List all warehouses (Holded API v2). All warehouses are returned in a single call (no cursor pagination). Supports field filtering and summary mode.
Inputs: fields, summary.
list_warehouse_stockB
List all products stock in a specific warehouse (Holded API v2). Cursor-paginated: pass the previous response nextCursor as cursor. Server-paginated; use limit to control page size. Supports field filtering to reduce response size.
Inputs: warehouseId (required), limit, cursor, fields, +1 more.
pause_employeeB
WRITE: starts a pause in the current working session of an employee (Holded API v2).
Inputs: employeeId (required).
pay_documentA
Register a payment for a document (Holded API v2). Supported docTypes: invoice, salesreceipt, creditnote, receiptnote, purchase — others throw an unsupported error. IMPORTANT: this may AUTO-APPROVE the document as a side effect (status 0→1). paymentmethod is the payment-method catalog id (from list_payment_methods), NOT a bank/treasury id. To link the payment to a bank account, pass bankId: the /payments endpoint can't set it, so the tool performs a second step (PUT /payments/{id}) and reports the outcome in _warnings.
Inputs: amount (required), docType (required), documentId (required), date, +3 more.
reconcile_bank_movementA
WRITE: reconciles a bank movement against documents/entries (Holded API v2, official endpoint — replaces the experimental reconcile_bank_transaction from the internal API when v2 is enabled). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Tesorería → Conciliar).
Inputs: data (required), accountId (required), movementId (required).
send_documentA
Send a document by email (Holded API v2). Supported docTypes: invoice, salesreceipt, creditnote, receiptnote, estimate, proform, salesorder, waybill, purchaseorder. purchase and purchaserefund are not supported in v2.
Inputs: docType (required), documentId (required), emails, message, +1 more.
ship_all_itemsA
Ship all items of a document (Holded API v2). salesorder → POST /sales-orders/{id}/ship. purchaseorder → POST /purchase-orders/{id}/receive (receive from supplier). All other docTypes are not supported in v2.
Inputs: docType (required), documentId (required).
ship_items_by_lineA
Ship specific items by line (Holded API v2). salesorder only → POST /sales-orders/{id}/ship-by-lines. purchaseorder line-level receive is UNVERIFIED in v2 and throws unsupported. All other docTypes are not supported.
Inputs: lines (required), docType (required), documentId (required).
unpause_employeeA
WRITE: ends the current pause of an employee working session (Holded API v2).
Inputs: employeeId (required).
update_bank_accountB
WRITE: updates a treasury bank account in Holded (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Tesorería → Actualizar cuenta).
Inputs: data (required), accountId (required).
update_contactC
Update an existing contact (Holded API v2)
Inputs: contactId (required), code, name, note, +6 more.
update_contact_groupC
Update an existing contact group (Holded API v2)
Inputs: groupId (required), name.
update_documentC
Update an existing document
Inputs: docType (required), documentId (required), date, items, +7 more.
update_document_pipelineA
Update pipeline stage for a document (Holded API v2). Uses PUT — verb changed from POST in v1. Supported for all docTypes except purchaserefund (v2 limitation). Route: PUT ${docBase}/{id}/pipeline.
Inputs: docType (required), stageId (required), documentId (required), pipelineId (required).
update_document_trackingA
Update tracking information for a document (Holded API v2). Supported docTypes: salesorder (PUT /sales-orders/{id}/tracking) and waybill (PUT /waybills/{id}/tracking). All other types have NO EQUIVALENT in v2 and will throw an unsupported error. NOTE: this is a discrepancy with the task brief (which stated "all types unsupported") — the normative annex tables show salesorder and waybill do have tracking in v2.
Inputs: docType (required), documentId (required), carrier, trackingNumber.
update_employeeB
WRITE: updates a real employee record in Holded (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Empleados → Actualizar).
Inputs: data (required), employeeId (required).
update_employee_contractB
WRITE: updates an employee's contract in Holded (API v2) — affects real HR/payroll data. data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Empleados → Actualizar contrato).
Inputs: data (required), employeeId (required).
update_employee_timeC
WRITE: updates a time-tracking record (Holded API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Control horario → Actualizar).
Inputs: data (required), timeId (required).
update_expenses_accountC
Update an existing expenses account (Holded API v2)
Inputs: accountId (required), code, name.
update_invoicing_forecastB
WRITE: updates an invoicing forecast in Holded cashflow (API v2). data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Tesorería → Previsiones).
Inputs: data (required), forecastId (required).
update_numbering_serieC
Update an existing numbering serie (Holded API v2)
Inputs: docType (required), serieId (required), name, prefix, +1 more.
update_paymentA
Update an existing payment (Holded API v2). IMPORTANT: Holded's PUT /payments/{id} REPLACES the record rather than merging, so any field omitted from the body is blanked. To prevent that, this tool first re-reads the current payment and merges your changes over it, preserving fields you did not pass (contactId, bankId, date, ...).
Inputs: paymentId (required), date, days, name, +3 more.
update_productC
Update an existing product (Holded API v2)
Inputs: productId (required), sku, tax, name, +4 more.
update_product_stockB
Update stock quantity for a product (Holded API v2). BREAKING CHANGE from v1: warehouse_id is now required; stock_variation replaces units; optional variant_id and description added.
Inputs: productId (required), warehouse_id (required), stock_variation (required), variant_id, +1 more.
update_salary_recordA
WRITE: updates a payroll record in Holded (API v2) — affects accounting and HR data. data is sent verbatim as the request body — see https://www.holded.com/es/desarrolladores/referencia-api (Registros de nómina → Actualizar).
Inputs: data (required), salaryRecordId (required).
update_sales_channelC
Update an existing sales channel (Holded API v2)
Inputs: channelId (required), name.
update_serviceC
Update an existing service (Holded API v2)
Inputs: serviceId (required), sku, tax, name, +2 more.
update_warehouseA
Update an existing warehouse (Holded API v2). BREAKING CHANGE from v1: HTTP verb changed from PUT to PATCH.
Inputs: warehouseId (required), city, name, address, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 119 tools
Many tools are cleanly distinct by resource and action, but several overlap explicitly: list_treasuries vs the bank_account tools, list_ledger_entries vs get_daily_ledger (same endpoint), and get_chart_of_accounts vs list_accounting_accounts (same endpoint). The descriptions helpfully flag these duplications and consolidation plans, which mitigates some misselection risk, but the boundaries remain unclear in practice.
Most tools follow a predictable list_/get_/create_/update_/delete_ + resource pattern (list_contacts, get_product, delete_payment, etc.). Some deviations exist (ship_all_items, clock_in_employee, reconcile_bank_movement, get_taxes plural, and the 'serie'/'series' inconsistency), but they are action verbs that stay readable.
119 tools is very high even for a full ERP surface covering contacts, documents, payroll, accounting, and treasury. Redundant pairs (treasury vs bank accounts, ledger vs daily ledger, chart of accounts vs ledger accounts) show bloat rather than strictly additive scope, with consolidation explicitly deferred to a later release.
Coverage is broad and lifecycle-complete across most domains (contacts, products, documents, payments, treasury, warehouses, payroll, accounting, contact groups, numbering series). A few gaps exist — purchaserefund has no full CRUD, purchase PDFs unsupported — but these are largely upstream API limitations that agents can work around.
Maintenance
Related MCP Connectors
Holded MCP server for ChatGPT, Claude and any AI agent: create invoice, send invoice, create expense, add contact and list unpaid invoices in your own Holded account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Holded yourself; Cotlet does not store your password and you need no Holded API key. About the official Holded API: Yes, Holded has a REST API, and it is only on paid plans (checked 14 Oct 2026). You create a key in Settings > Developers > Credentials > Add API Token, choose read, write or full access per module, and the plan sets a monthly call limit. Setup and FAQ: https://cotlet.dev/integrations/holded-api-mcp-server
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
MCP server for Codat — companies, connections, invoices, bills and financial statements.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that connects Claude Code to the Holded API for natural language financial, accounting, and invoicing queries, with built-in Spanish PGC context.132Apache 2.0
- AlicenseBqualityDmaintenanceMCP server for Invoice Ninja v5 API. Enables AI assistants to manage clients, invoices, quotes, payments, and time tracking through natural language.3220 npm2MIT
- AlicenseNot gradedqualityDmaintenanceModel Context Protocol (MCP) server for SuperFaktura invoicing system. Enables AI assistants to interact with SuperFaktura API for managing invoices, clients, and expenses.Apache 2.0
- AlicenseBqualityBmaintenanceMCP server for Holded API v2, enabling listing and querying of contacts, invoices, purchases, products, services, and payments, with low-level access to any endpoint.15141 npm1MIT