MCP Holded

MCP Holded

Model Context Protocol server for [Holded](https://www.holded.com), on the v2 API

_A community project. Not affiliated with, endorsed by, or supported by Holded. "Holded" and the Holded logo are trademarks of their owner, used here to identify the API this server speaks to._

An MCP server for the Holded API v2: contacts, sales and purchase documents, payments, treasury, accounting, catalog, team, CRM, projects, calendar, inbox and webhooks. Thirteen hierarchical tools with an action parameter, Zod validation of every request and response, retries on reads, and a confirmation gate on every destructive operation.

Holded deprecated its classic API (/api/invoicing/v1, key header). New keys use the format pat_ _ and only authenticate against v2 (https://api.holded.com/api/v2, Authorization: Bearer). This server speaks v2 only.

Why this one

• v2 only, which is the API that still works. Holded deprecated the classic API (/api/invoicing/v1, key header). New tokens are pat_ _ and authenticate only against v2. This server speaks v2 and nothing else.
• Thirteen hierarchical tools with an `action` parameter, not one tool per endpoint, so the tool list stays small in a model's context while covering contacts, sales, purchases, payments, treasury, accounting, catalog, team, CRM, projects, calendar, inbox and webhooks.
• Seven MCP resources and six MCP prompts. The resources carry the account's own tax keys, numbering series, payment methods and chart of accounts, plus the API behaviour a schema cannot express. The prompts run the real workflows: aged receivables, VAT summary, bank reconciliation, statements, month-end close.
• A confirmation gate on every destructive operation, with a structural test that keeps the documented list equal to the code. Nothing that deletes, overwrites, approves or emails goes through without confirm: true.
• Zod validation of every request and every response. A shape the server has not seen surfaces as a clear schema error rather than a silent success.
• Over 200 tests against anonymised real v2 responses, npm provenance via trusted publishing, and Node 20 or later.

How it compares

Four MCP servers for Holded exist on npm. This compares the published code of each, not their descriptions, as at 2026-09-08: @t4dhg/mcp-holded 2.1.1, @nubiia/mcp-holded 2.0.2, @energio/holded-mcp 1.5.1 and holded-mcp 1.0.0. It is a snapshot and will age; check the current versions yourself before relying on it.

Where this differs most: the v1 servers are on an API Holded has deprecated, and new pat_ tokens do not authenticate against it at all, so they cannot work with a newly issued key. Against @nubiia/mcp-holded, which is current, the differences are breadth (this server covers calendar and bookings, inbox, webhooks, and CRM leads and funnels, none of which appear in nubiia's tool list), the resource and prompt surface, the hierarchical tool shape, and a gated raw-request escape hatch. Nubiia's own Node floor is 22.14, genuinely higher than the 18 this server and holded-mcp both support.

Quick start

Install nothing. Every client below runs the server through npx. Create the token in Holded under Settings, Developers, API and use the full pat_..._... value.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:

{

"mcpServers": { "holded": { "command": "npx", "args": ["-y", "@t4dhg/mcp-holded"], "env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" } } } }

Claude Code

claude mcp add holded --env HOLDED_API_KEY=pat_xxxxxxxx_xxxxxxxx -- npx -y @t4dhg/mcp-holded

Cursor

Edit ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:

{

"mcpServers": { "holded": { "command": "npx", "args": ["-y", "@t4dhg/mcp-holded"], "env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" } } } }

VS Code

Edit .vscode/mcp.json. Note the key is servers, not mcpServers:

{

"servers": { "holded": { "command": "npx", "args": ["-y", "@t4dhg/mcp-holded"], "env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" } } } }

Requires Node.js 20 or later. Development uses Node 24 (nvm use).

Typed request collections accept at most 1,000 items, including nested collections. Existing lower API limits still apply (bank movement batches accept at most 100). A tool call may contain at most 10,000 combined array elements and object members, including arbitrary JSON payloads. Split larger operations into smaller calls.

Environment variables

What people use it for

Chasing unpaid invoices. Run the holded_aged_receivables prompt. You get every outstanding invoice bucketed by how late it is and grouped by customer, worst first, counting only the unpaid remainder of part-paid invoices. Then ask for a statement for the worst offender with holded_contact_statement, in a form you can send them.

Reconciling a bank month. Run holded_bank_reconciliation for the period. It matches bank movements against recorded payments on amount and date, then shows you the two lists that matter: m