@t4dhg/mcp-holded

An MCP server for the Holded API v2.

Holded deprecated its classic API (base https://api.holded.com/api/invoicing/v1 with a key: <apikey> header). New Holded keys use the format pat_<id>_<secret> and only authenticate against the v2 API (https://api.holded.com/api/v2) with an Authorization: Bearer <key> header. Servers written for the old API reject new keys with {"status":0,"info":"Invalid key"}. This server speaks v2.

Install and configure

Add it to your MCP client config (for example .mcp.json or Claude Desktop's config):

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

Requires Node.js >= 18.

Getting a key

Create a Personal Access Token in Holded under Settings, Developers, API. Use the full pat_..._... value as HOLDED_API_KEY.

Related MCP server: MCP Holded

Environment variables

Tools

The list tools accept optional page, limit, and query (free-text search). Holded's v2 API exposes far more than the resources with dedicated tools above; use holded_request to reach any of them, for example { "method": "GET", "path": "/numberingseries" }.

A note on unknown paths

api.holded.com serves its single-page web app (HTML) with an HTTP 200 status for paths that do not exist in v2. This server detects an HTML body and returns a clear error instead, so a wrong path fails loudly rather than looking like an empty success.

Development

npm install
HOLDED_API_KEY=pat_..._... npm run smoke

smoke-test.mjs spawns the server over stdio, lists its tools, and makes one live call.

License

MIT