holded-mcp

Holded MCP Server

A Model Context Protocol (MCP) server for integrating with the Holded API. This server provides comprehensive access to Holded's business management platform, including invoicing, accounting, CRM, projects, and team functionality.

Table of Contents

• Features
• Installation
• Configuration
• Usage
• Available Tools
• Document Types
• Response Formats
• Error Handling
• Performance
• Development
• Contributing
• License
• Support

Features

Invoicing Module

• Documents: Full CRUD operations for documents (invoices, estimates, purchases, etc.) plus pay, send, PDF export, tracking, and pipeline management
• Contacts: Full CRUD operations for contacts and contact groups
• Products: Manage products, variants, and stock levels
• Payments: Full CRUD operations for payments
• Numbering Series: Full CRUD operations for document numbering series
• Treasury: Create, list, and retrieve treasury/bank accounts
• Payment Methods: List available payment methods
• Expenses Accounts: Full CRUD operations for expenses accounts
• Sales Channels: Full CRUD operations for sales channels
• Services: Full CRUD operations for services
• Taxes: Get tax information and rates
• Warehouses: Full CRUD operations for warehouses

CRM Module

• Leads: Create, list, get, update, delete leads; manage stages, notes, and tasks
• Funnels: Full CRUD operations for sales funnels with custom stages
• Events: Full CRUD operations for CRM events
• Bookings: Full CRUD operations for bookings and manage locations

Projects Module

• Projects: Full CRUD operations for projects plus project summaries
• Tasks: Full CRUD operations for project tasks
• Time Tracking: Full CRUD operations for project time tracking entries

Accounting Module

• Accounts: List and create accounting accounts with prefix-based numbering
• Daily Ledger: List daily ledger entries and create accounting entries

Team Module

• Employees: Full CRUD operations for employees
• Time Tracking: List all time trackings, list by employee, get, create, update, and delete time tracking entries

Installation

Prerequisites

1. Node.js >= 20 (check with node --version)
2. Holded API Key - Get yours from Holded API Settings or go to Configuration (top bar) → API

Quick Start (npx)

The easiest way to use this MCP server is via npx - no installation or build required! Just configure your MCP client as shown below.

Setup for Claude Desktop

Add the following to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop to load the server.

Setup for Claude Code

Add the server with a single command:

claude mcp add holded -- npx -y @energio/holded-mcp

Then set the API key in your environment:

export HOLDED_API_KEY=your_api_key_here

Setup for Cursor

Add the following to your Cursor MCP settings file:

• macOS: ~/.cursor/mcp.json
• Windows: %APPDATA%\Cursor\mcp.json
• Linux: ~/.config/cursor/mcp.json

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

After saving, restart Cursor or reload the MCP servers from the settings.

Setup for VS Code

Add the following to your VS Code user settings (settings.json) or workspace settings (.vscode/mcp.json):

User settings (settings.json):

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

Workspace settings (.vscode/mcp.json):

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

Setup for Windsurf

Add the following to your Windsurf MCP configuration file:

• macOS: ~/.codeium/windsurf/mcp_config.json
• Windows: %APPDATA%\Codeium\windsurf\mcp_config.json
• Linux: ~/.codeium/windsurf/mcp_config.json

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

Setup for Other MCP-Compatible Agents

Any MCP-compatible agent can use this server via npx. The general configuration requires:

1. Command: npx
2. Arguments: ["-y", "@energio/holded-mcp"]
3. Environment variable: HOLDED_API_KEY with your API key

Example configuration:

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

The server communicates via stdio using the MCP protocol and can be integrated with any client that supports the Model Context Protocol.

Configuration

The server requires a HOLDED_API_KEY environment variable. This is typically set in your MCP client configuration (see installation sections above).

For manual/development usage, you can set it directly:

export HOLDED_API_KEY=your_api_key_here

Module Selection

By default, all modules are enabled. To load only specific modules, set the HOLDED_MODULES environment variable with a comma-separated list:

Available modules: invoicing, crm, projects, accounting, team

Example - enable only invoicing module:

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@energio/holded-mcp"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here",
        "HOLDED_MODULES": "invoicing"
      }
    }
  }
}

Configuration examples:

• All modules (default): Omit HOLDED_MODULES or leave it empty
• Only CRM: "HOLDED_MODULES": "crm"
• Only invoicing: "HOLDED_MODULES": "invoicing"
• Multiple modules: "HOLDED_MODULES": "invoicing,crm"

Debug Mode

Enable debug logging for API requests and retries by setting the HOLDED_DEBUG environment variable:

{
  "mcpServers": {
    "holded": {
      "command": "npx",
      "args": ["-y", "@energio/holded-mcp"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here",
        "HOLDED_DEBUG": "true"
      }
    }
  }
}

When enabled, the server will log retry attempts and API request failures to stderr, which can be helpful for troubleshooting connection issues or rate limiting.

Usage

Running the Server Manually

npm start

Or for development with auto-reload:

npm run dev

Note: In most cases, you won't run the server manually. Your MCP client (Cursor, Claude Desktop, etc.) will start and manage the server process automatically based on your configuration.

Available Tools

Contact Tools

• holded_invoicing_list_contacts - List all contacts
• holded_invoicing_get_contact - Get a specific contact
• holded_invoicing_create_contact - Create a new contact
• holded_invoicing_update_contact - Update a contact
• holded_invoicing_delete_contact - Delete a contact
• holded_invoicing_list_contact_groups - List contact groups
• holded_invoicing_get_contact_group - Get a contact group
• holded_invoicing_create_contact_group - Create a contact group
• holded_invoicing_update_contact_group - Update a contact group
• holded_invoicing_delete_contact_group - Delete a contact group
• holded_invoicing_list_contact_attachments - List attachments for a contact
• holded_invoicing_get_contact_attachment - Get a specific contact attachment
• holded_invoicing_upload_contact_attachment - Upload an attachment to a contact

Product Tools

• holded_invoicing_list_products - List all products
• holded_invoicing_get_product - Get a specific product
• holded_invoicing_create_product - Create a new product
• holded_invoicing_update_product - Update a product
• holded_invoicing_delete_product - Delete a product
• holded_invoicing_list_products_stock - List product stock levels for a specific warehouse
• holded_invoicing_update_product_stock - Update product stock
• holded_invoicing_get_product_image - Get main product image
• holded_invoicing_list_product_images - List all product images
• holded_invoicing_get_product_secondary_image - Get a secondary product image
• holded_invoicing_upload_product_image - Upload an image to a product

Document Tools

• holded_invoicing_list_documents - List documents by type
• holded_invoicing_get_document - Get a specific document
• holded_invoicing_create_document - Create a new document
• holded_invoicing_update_document - Update a document
• holded_invoicing_delete_document - Delete a document
• `holded_inv

---

README truncated. View full README on GitHub.