mcp-holded

<p align="center">
  <img src="https://raw.githubusercontent.com/t4dhg/mcp-holded/main/assets/holded-logo.svg" alt="Holded" height="28">
</p>

# MCP Holded

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/t4dhg/mcp-holded/actions/workflows/ci.yml/badge.svg)](https://github.com/t4dhg/mcp-holded/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/t4dhg/mcp-holded/branch/main/graph/badge.svg)](https://codecov.io/gh/t4dhg/mcp-holded)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org/)
[![npm version](https://img.shields.io/npm/v/@t4dhg/mcp-holded.svg)](https://www.npmjs.com/package/@t4dhg/mcp-holded)
[![npm downloads](https://img.shields.io/npm/dm/@t4dhg/mcp-holded.svg)](https://www.npmjs.com/package/@t4dhg/mcp-holded)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)

_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](https://modelcontextprotocol.io) 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_<id>_<secret>` 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_<id>_<secret>` 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 18 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.

|                              | `@t4dhg/mcp-holded`                                  | `@nubiia/mcp-holded`                                                             | `@energio/holded-mcp`                                       | `holded-mcp`                                                |
| ---------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| API version                  | **v2**                                               | **v2**                                                                           | v1 (deprecated)                                             | v1 (deprecated)                                             |
| Auth                         | Bearer `pat_`                                        | Bearer `pat_`                                                                    | `key` header                                                | `key` header                                                |
| Domains covered              | 13                                                   | 18 tool-module files (no calendar, bookings, inbox, webhooks or CRM)             | 5 API sections (accounting, CRM, invoicing, projects, team) | 5 API sections (accounting, CRM, invoicing, projects, team) |
| Tool shape                   | 13 hierarchical, `action` parameter (15 tools total) | 119 flat tools, one per operation                                                | 139 flat tools, one per operation                           | 136 flat tools, one per operation                           |
| MCP resources                | **7**                                                | 0                                                                                | 0                                                           | 0                                                           |
| MCP prompts                  | **6**                                                | 0                                                                                | 0                                                           | 0                                                           |
| Destructive operations gated | Every one, structurally tested                       | No confirmation gate; `destructiveHint` annotation and per-tool rate limits only | No confirmation gate; `destructiveHint` annotation only     | No confirmation gate; `destructiveHint` annotation only     |
| Response validation          | Zod, requests and responses                          | Zod, requests only                                                               | Zod, requests only                                          | Zod, requests only                                          |
| Minimum Node                 | **18**                                               | 22.14                                                                            | 20                                                          | **18**                                                      |
| Tests                        | 234                                                  | 389, across 23 files, shipped in the package and passing                         | None shipped                                                | None shipped                                                |
| npm provenance               | Yes                                                  | Yes                                                                              | No                                                          | No                                                          |
| Licence                      | MIT                                                  | MIT                                                                              | MIT                                                         | MIT                                                         |
| Last publish                 | 2026-09-08                                           | 2026-07-07                                                                       | 2026-07-01                                                  | 2026-02-25                                                  |

<!-- Re-verify every cell against the rivals' published tarballs before editing this section. Do not edit a single cell without re-running the whole pass; a half-updated table is worse than a stale one. -->

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:

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

### Claude Code

```bash
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:

```json
{
  "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`:

```json
{
  "servers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "