Holded MCP Server

An open-source Model Context Protocol (MCP) server for the Holded API. Connect any MCP-compatible AI assistant to your Holded account and manage invoicing, CRM, projects, team, and accounting through natural language.

Built with Python, FastMCP, and httpx.

Features

• Invoicing — Create and manage invoices, estimates, sales orders, credit notes, receipts, proformas, and purchase documents.
• Contacts — Full CRUD for clients, suppliers, leads, debtors, and creditors.
• Products — Manage your product catalog, pricing, stock levels across warehouses.
• CRM — Work with sales funnels, leads/deals, and activities.
• Projects — Create projects, tasks, and track time.
• Team / HR — Manage employees, clock in/out, and attendance records.
• Accounting — Access the chart of accounts and daily ledger entries.
• Treasury — List and create bank/cash accounts.

Setup

Prerequisites

• Python 3.10+
• A Holded account with an API key (Settings > API)

Installation

pip install -e .

# Set your Holded API key
export HOLDED_API_KEY=your_api_key_here

Configuration

HOLDED_API_KEY (required)

Your Holded API key. You can find it in Holded under Settings > API.

HOLDED_ALLOWED_METHODS (optional)

Controls which HTTP methods the server is permitted to use. This acts as a safety mechanism to prevent unintended write or delete operations.

Value	Behavior
ALL (default)	All methods allowed — full read/write/delete access
GET	Read-only mode — only list and get operations work
GET,POST	Read + create — no updates or deletions
GET,POST,PUT	Read, create, and update — no deletions
GET,POST,PUT,DELETE	Same as ALL — explicit full access

Examples:

# Read-only mode (safe for exploration)
export HOLDED_ALLOWED_METHODS=GET

# Allow reads and creating new records
export HOLDED_ALLOWED_METHODS=GET,POST

# Full access (default)
export HOLDED_ALLOWED_METHODS=ALL

Tip: Start with GET to safely explore your data, then expand permissions as needed.

Usage

Claude Code

claude mcp add holded -- python -m holded_mcp.server

Or add to .claude/settings.json:

{
  "mcpServers": {
    "holded": {
      "command": "python",
      "args": ["-m", "holded_mcp.server"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "holded": {
      "command": "python",
      "args": ["-m", "holded_mcp.server"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "holded": {
      "command": "python",
      "args": ["-m", "holded_mcp.server"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings (.vscode/mcp.json):

{
  "servers": {
    "holded": {
      "command": "python",
      "args": ["-m", "holded_mcp.server"],
      "env": {
        "HOLDED_API_KEY": "your_api_key_here"
      }
    }
  }
}

Any MCP-Compatible Client

The server uses stdio transport by default. Run it with any MCP client that supports stdio:

python -m holded_mcp.server

Or use the installed entry point:

holded-mcp

Available Tools

Contacts

list_contacts, get_contact, create_contact, update_contact, delete_contact

Documents

list_documents, get_document, create_document, update_document, delete_document, pay_document, send_document, get_document_pdf

Document types: invoice, salesreceipt, creditnote, estimate, salesorder, waybill, proform, purchase, purchaserefund, purchaseorder

Products

list_products, get_product, create_product, update_product, delete_product, update_stock

Treasury

list_treasuries, create_treasury

CRM

list_funnels, list_leads, get_lead, create_lead, update_lead, delete_lead, list_events, create_event

Projects

list_projects, get_project, create_project, update_project, delete_project, list_tasks, create_task, update_task, list_time_records, create_time_record

Team

list_employees, get_employee, create_employee, update_employee, clock_in, clock_out, list_time_entries

Accounting

list_daily_ledger, create_ledger_entry, list_accounts, get_account, create_account

Use Cases

• Automate invoicing — Ask your AI assistant to create invoices, send them to clients, and track payments.
• CRM management — Manage your sales pipeline, create leads, and log activities without leaving your editor.
• Project tracking — Create projects and tasks, log time, and monitor progress through conversation.
• HR operations — Manage employees, track attendance, and handle clock in/out.
• Financial overview — Query your chart of accounts, review ledger entries, and manage treasury accounts.
• Bulk operations — Use AI to process multiple records, generate reports, or migrate data.

Architecture

The server follows a modular architecture:

• Entry point (server.py) — Creates the FastMCP instance and registers all tool modules.
• API client (client.py) — Async HTTP client with auth, method restrictions, and pagination support.
• Tool modules (tools/*.py) — Each module exports a register(mcp, client) function. Modules are purely functional with no cross-dependencies.

Author

Built by Javier Chulvi.

License

MIT