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.

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.

• Node.js 22.14 or higher
• A Holded account with API access
• A Holded API v2 key (pat_… or sk_live_…) — generate it in Holded → Settings → API

npm install -g @nubiia/mcp-holded

git clone https://github.com/nubiia-dev/mcp-holded.git
cd mcp-holded
npm install
npm run build

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_here

Generate 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_b

TENANT_N_API_KEY_V2 is accepted as an alias for TENANT_N_API_KEY (wins if both are set).

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"
      }
    }
  }
}

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.

List tools changed from page-based to cursor-based pagination:

Responses now follow this envelope:

{
  "items": [...],
  "nextCursor": "opaque-string-or-null",
  "hasMore": true
}

Iterate by passing nextCursor as cursor until hasMore is false.

• Field names are snake_case throughout (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.

Attachments are now fetched by filename instead of attachment ID. Use get_contact_attachment with the filename field returned by list_contact_attachments.

Once configured, you can ask Claude to:

• "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"

• "List all my clients in Holded"
• "Create a new client named Acme Corp"
• "Update the email for contact #123"

• "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"

• "List all employees"
• "Clock in employee #456"
• "Get the salary record for employee #789 for June 2025"

• "Get all my taxes"
• "List all treasury bank accounts"
• "Show me the daily ledger for January 2025"
• "Get the chart of accounts"

The API supports these document types:

https://api.holded.com/api/

The server routes each tool to the appropriate v2 sub-path (e.g. /invoicing/v2/, /team/v2/, /accounting/v2/).

All requests use Bearer authentication with your v2 key:

Authorization: Bearer pat_your_v2_key_here

List endpoints use cursor-based pagination via limit and cursor arguments (see Migrating from 1.x).

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

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.

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.

For questions, issues, or feature requests:

• GitHub Issues: Report an issue
• Email: hola@nubiia.es
• Documentation: Holded API Docs

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

MIT - See LICENSE file for details.

Built by Nubiia — nubiia.es · hola@nubiia.es

Maintainer: Samuel Fraga — GitHub · LinkedIn

• Nubiia — AI automation & integrations
• Holded API Documentation
• MCP Specification
• Privacy Policy