MCP Holded
Model Context Protocol server for Holded, on the v2 API
에이전트 강화
게시자의 자체 명령입니다. PlugMCP 엔드포인트가 아닙니다.
Host a copy with our keys and logs.
npx -y @t4dhg/[email protected]Claude Code에는 로컬 명령용 설치 링크가 없습니다. 아래 명령을 복사해 터미널에서 실행합니다.
HOLDED_API_KEY=<secret> HOLDED_BASE_URL=<value> HOLDED_TIMEOUT_MS=<value> HOLDED_MAX_RETRIES=<value> DEBUG=<value> claude mcp add io.github.t4dhg-mcp-holded -- npx -y @t4dhg/mcp-holded@4.0.0터미널에서 실행합니다.
{ "mcpServers": { "io.github.t4dhg-mcp-holded": { "command": "npx", "args": [ "-y", "@t4dhg/[email protected]" ], "env": { "HOLDED_API_KEY": "<secret>", "HOLDED_BASE_URL": "<value>", "HOLDED_TIMEOUT_MS": "<value>", "HOLDED_MAX_RETRIES": "<value>", "DEBUG": "<value>" } } }}claude_desktop_config.json
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행게시자 제공
Model Context Protocol server for Holded, on the v2 API
MCP server for Holded (Spanish ERP): invoicing, accounting, treasury, CRM, projects, payroll.
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 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.
/api/invoicing/v1, key header). New tokens are pat_<id>_<secret> and authenticate only against v2. This server speaks v2 and nothing else.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.confirm: true.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.
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.
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.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:
{
"mcpServers": {
"holded": {
"command": "npx",
"args": ["-y", "@t4dhg/mcp-holded"],
"env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" }
}
}
}
claude mcp add holded --env HOLDED_API_KEY=pat_xxxxxxxx_xxxxxxxx -- npx -y @t4dhg/mcp-holded
Edit ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:
{
"mcpServers": {
"holded": {
"command": "npx",
"args": ["-y", "@t4dhg/mcp-holded"],
"env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" }
}
}
}
Edit .vscode/mcp.json. Note the key is servers, not mcpServers:
{
"servers": {
"holded": {
"command": "npx",
"args": ["-y", "@t4dhg/mcp-holded"],
"env": { "HOLDED_API_KEY": "pat_xxxxxxxx_xxxxxxxx" }
}
}
}
Requires Node.js 18 or later.
Chasing unpaid invoices. Run the holded_aged_receivables prompt. You get every outstanding invoice bucketed by how late it is and grouped by customer, worst first, counting only the unpaid remainder of part-paid invoices. Then ask for a statement for the worst offender with holded_contact_statement, in a form you can send them.
Reconciling a bank month. Run holded_bank_reconciliation for the period. It matches bank movements against recorded payments on amount and date, then shows you the two lists that matter: movements with no payment recorded, and payments the bank has not shown. Reconciling stays behind a confirmation, so nothing is matched in your books until you approve it.
Preparing the quarterly VAT figures. Run holded_vat_summary. It groups sales and purchases by tax key for the quarter and gives base and quota for each, which is the shape Modelo 303 wants. It is a working aid, not a filing, and it says so.
Closing a month. Run holded_month_end_close. It tells you what is still in draft, what is past due, and what is sitting in the inbox, each with the exact call that clears it.
Every tool takes an action. List actions accept limit (1 to 200) and cursor; the response says how to continue. Create and update actions take the payload in data, following the Holded v2 request contract, and return the record re-read from the API. Gated actions take confirm: true.
{
"action": "list",
"type": "invoice",
"status": "pending",
"start_date": "2026-01-01",
"sort": "-date",
"limit": 50
}
{
"action": "create",
"type": "invoice",
"data": {
"contact_id": "5ff44eb88ec0b10f326e3213",
"date": "2026-09-06",
"items": [{ "name": "Licence", "units": 1, "price": 1000, "taxes": ["s_iva_21"] }]
}
}
Seven MCP resources give a model the context it needs before it can make a correct call. Attach them in your client, or read them by URI.
The three guides are static. The four references read the account's own configuration and are cached for fifteen minutes, because clients re-read resources at the start of every conversation. A reference whose read fails returns an explanation and the tool to fall back to; it never throws.
Six MCP prompts run the workflows this server exists for. Each one pre-reads the facts and hands back a report plus the exact tool calls to act on it. None of them writes. Where a change is needed, the prompt emits the gated call for you to approve.
These actions delete, overwrite, lock or email something. Without confirm: true the tool sends nothing and explains what would happen; the same call with confirm: true proceeds. A structural test keeps this list equal to the gated actions in the code.
holded_contacts({ action: 'update' }), holded_contacts({ action: 'delete' }), holded_contacts({ action: 'bulk_archive' }), holded_contacts({ action: 'bulk_delete' }), holded_contacts({ action: 'update_group' }), holded_contacts({ action: 'delete_group' })holded_sales({ action: 'update' }), holded_sales({ action: 'delete' }), holded_sales({ action: 'approve' }) (assigns the legal number; irreversible under Verifactu), holded_sales({ action: 'cancel' }), holded_sales({ action: 'send' }) (emails the customer), holded_sales({ action: 'set_pipeline' }), holded_sales({ action: 'skip' }), holded_sales({ action: 'bulk_approve' }), holded_sales({ action: 'bulk_cancel' }), holded_sales({ action: 'bulk_delete' })holded_purchases({ action: 'update' }), holded_purchases({ action: 'delete' }), holded_purchases({ action: 'approve' }), holded_purchases({ action: 'send' }), holded_purchases({ action: 'set_pipeline' })holded_payments({ action: 'update' }), holded_payments({ action: 'delete' })holded_treasury({ action: 'update_account' }), holded_treasury({ action: 'archive_account' }), holded_treasury({ action: 'delete_account' }), holded_treasury({ action: 'reconcile' }), holded_treasury({ action: 'update_forecast' }), holded_treasury({ action: 'delete_forecast' })holded_accounting({ action: 'update_expenses_account' }), holded_accounting({ action: 'delete_expenses_account' }), holded_accounting({ action: 'update_sales_channel' }), holded_accounting({ action: 'delete_sales_channel' }), holded_accounting({ action: 'update_numbering_series' }), holded_accounting({ action: 'delete_numbering_series' }), holded_accounting({ action: 'delete_tag' })holded_catalog({ action: 'update_product' }), holded_catalog({ action: 'update_stock' }), holded_catalog({ action: 'delete_product' }), holded_catalog({ action: 'update_service' }), holded_catalog({ action: 'delete_service' }), holded_catalog({ action: 'update_warehouse' }), holded_catalog({ action: 'delete_warehouse' }), holded_catalog({ action: 'update_price_list' }), holded_catalog({ action: 'delete_price_list' }), holded_catalog({ action: 'update_production_order' }), holded_catalog({ action: 'delete_production_order' })holded_team({ action: 'delete_payslip_payment' })holded_crm({ action: 'update_funnel' }), holded_crm({ action: 'delete_funnel' }), holded_crm({ action: 'update_lead' }), holded_crm({ action: 'delete_lead' }), holded_crm({ action: 'move_stage' }), holded_crm({ action: 'update_dates' }), holded_crm({ action: 'update_note' }), holded_crm({ action: 'update_task' }), holded_crm({ action: 'delete_task' })holded_projects({ action: 'update_project' }), holded_projects({ action: 'delete_project' }), holded_projects({ action: 'update_task' }), holded_projects({ action: 'delete_task' }), holded_projects({ action: 'update_time' }), holded_projects({ action: 'delete_time' })holded_calendar({ action: 'update_event' }), holded_calendar({ action: 'delete_event' }), holded_calendar({ action: 'update_booking' }), holded_calendar({ action: 'cancel_booking' })holded_inbox({ action: 'update' }), holded_inbox({ action: 'attach' }), holded_inbox({ action: 'delete' })holded_webhooks({ action: 'update' }), holded_webhooks({ action: 'disable' }), holded_webhooks({ action: 'delete' })Creates are not gated, including record_payment, create_movements and create_ledger_entry: they add records that can be deleted afterwards. The gate reduces accidents; it is not an authorization boundary, and the token grants whatever Holded grants it.
holded_request reaches every v2 endpoint with correct Bearer auth and returns the response unvalidated. DELETE, PUT and PATCH require confirm: true, and so does a POST to any path containing bulk, cancel, archive, approve, send, reconcile, ship, skip, clock-in or clock-out, because Holded hides destructive operations behind those. The refused call returns the exact method, URL and body it would have sent.
Everything below was verified against live v2 responses on 2026-09-06 and is what the schemas are built from.
{ items, cursor, has_more }; cursor is the last item id and goes back as ?cursor=. limit defaults to 50 and is capped at 200; page and offset are ignored. Configuration lists (taxes, tags, warehouses, accounting accounts, expenses accounts, sales channels, numbering series, price lists, booking locations) return { items } with no cursor.DD/MM/YYYY. Everything else is ISO 8601.{ type, title, status, detail }) for 400, 403 and 404. A bad or missing key gives 403 "Access denied", not 401. Unknown routes give 404 { message: "No route found..." }. Some malformed paths return Holded's HTML app shell with a 200 or 405; the server turns that into an error instead of returning HTML.query, q and search on /contacts filter nothing; use search (which calls /contacts/search?name=) or the exact-match filters.accounting_date, approved_at, notes, language, payments_detail, payments_refunds, shipping, design_id, pipeline_id and more./purchase-refunds but read and created under /purchases/refund, and offer nothing else (no update, delete, pdf, attachments or approve). Purchases have no pdf or send route. Recurring invoices have update, delete, skip and schedule only. Estimates, proformas, orders and waybills have no payments. The tools refuse an unsupported combination with a message listing what is available, before sending anything.Retry-After), 5xx, timeouts and network errors with exponential backoff and jitter. Writes are sent exactly once because Holded has no idempotency key.{ id } with a 201. The server re-reads the record so the tool returns the validated object.HOLDED_API_KEY must be a v2 Personal Access Token, in the form pat_<id>_<secret>. The server checks this at startup and refuses to run on anything else, rather than failing later on every call. A classic v1 key is 32 hex characters and does not authenticate against v2 at all.
That is what a bad, revoked or wrong-scope token looks like on v2. Holded returns 403, not 401, so it reads like a permissions problem when it is usually an authentication one. Regenerate the token in Holded under Settings, Developers, API, and check you copied the whole pat_..._... value including both underscores.
Not every verb exists for every type. Purchase refunds have no update, delete, pdf, attachment or approve. Purchases have no pdf or send. Recurring invoices have only update, delete, skip and schedule. Estimates, proformas, sales orders and waybills have no payments. The tool refuses before sending anything and lists what is available. The full matrix is in the holded://guide/document-types resource.
It probably is. Holded silently ignores undocumented query parameters: query, q and search on /contacts filter nothing and return everything. Use the search action, which calls /contacts/search?name=, or the exact-match filters email, code, phone, mobile and custom_id. page and offset are ignored everywhere; pagination is by cursor.
The four holded://reference/... resources read live configuration, so they need a working token. They return an explanation rather than throwing, so the server keeps working. The three holded://guide/... resources are static and always readable.
DEBUG=trueEvery request is then logged to stderr. Never to stdout, which is the MCP transport.
Does it work with the old v1 API key? No, deliberately. v1 is deprecated and new keys do not authenticate against it. Supporting both would mean two code paths where one is a dead end.
Can it delete things by accident? Every operation that deletes, overwrites, approves, cancels or emails requires confirm: true. Without it the tool sends nothing and tells you what it would have done. The list is generated from the code into holded://guide/irreversible-operations, and a test fails if the documented list and the code disagree.
What happens if a write times out? It is not retried. Holded has no idempotency key, so a retried write could double-charge or double-issue. Reads retry with backoff; writes are sent exactly once. If a write times out, read the record before trying again.
Why does approving an invoice need confirmation? It assigns the legal invoice number. Under Verifactu that is part of an immutable chained record and cannot be undone: a mistake needs a credit note, not an edit.
Are amounts safe to round-trip? Yes. Amounts are strings and the server passes them through unchanged, so nothing is rounded. Be aware there are two conventions: documents and salary records use a comma, payments, treasury and accounting use a dot.
Can I reach an endpoint that has no dedicated action? Yes, holded_request reaches any v2 path with correct auth. Destructive methods and paths are gated there too.
Is it affiliated with Holded? No. It is a community project that speaks their public API.
npm install
npm run lint && npm run typecheck && npm run format:check && npm test && npm run build
HOLDED_API_KEY=pat_..._... npm run smoke # spawns the built server over stdio and makes one read call
Tests run against anonymised fixtures in src/__tests__/fixtures, each a real v2 response with names, tax ids, addresses, bank details and amounts replaced. Add a fixture when you add an endpoint; the schema test fails on any fixture without a schema.
Releases are staged by CI and promoted by a human. Bump package.json, commit, tag vX.Y.Z and push the tag. The publish workflow authenticates to npm over OIDC as a trusted publisher (no token anywhere), runs tests and build, and runs npm stage publish. Nothing is installable until a maintainer runs npm stage approve <stage-id> locally, which is where 2FA is proved. See CONTRIBUTING.md for the exact steps.
Report vulnerabilities through GitHub Security Advisories; see SECURITY.md.
MIT
MCP server for Holded (Spanish ERP): invoicing, accounting, treasury, CRM, projects, payroll.
{ "mcpServers": { "io.github.t4dhg-mcp-holded": { "command": "npx", "args": [ "-y", "@t4dhg/[email protected]" ], "env": { "HOLDED_API_KEY": "<secret>", "HOLDED_BASE_URL": "<value>", "HOLDED_TIMEOUT_MS": "<value>", "HOLDED_MAX_RETRIES": "<value>", "DEBUG": "<value>" } } }}도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
게시자가 등록한 환경 변수: HOLDED_API_KEY, HOLDED_BASE_URL, HOLDED_TIMEOUT_MS, HOLDED_MAX_RETRIES, DEBUG.
MCP Holded은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-11-16. MCP server for Holded (Spanish ERP): invoicing, accounting, treasury, CRM, projects, payroll.