Dolibarr MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Dolibarr MCP
Most MCP servers for business software are thin 1:1 wrappers around a REST API, which leaves the model to chain calls, look up IDs, and work out the business logic itself. This server takes the opposite approach. Each tool performs a complete business operation: creating and validating a quote, recording a payment, logging time on a project task, or producing an aged receivables overview. It accepts fuzzy inputs like client names instead of numeric IDs, resolves foreign keys server-side, and returns denormalized, human-readable data. It runs as a Docker sidecar next to your Dolibarr instance, speaks Streamable HTTP, and keeps your data on your own infrastructure. Destructive operations are off by default and are enabled with MCP_ALLOW_DELETES=true. Built and used in production by Stormlabs.
Setup
Install dependencies:
npm installCreate a local environment file:
cp .env.example .envFill in these values:
Variable
Description
MCP_API_KEYSecret expected from MCP clients in the
X-API-Keyheader, or asAuthorization: Bearer <secret>.DOLIBARR_URLFull Dolibarr REST API base URL, for example
http://host.docker.internal/api/index.php.DOLIBARR_API_KEYAPI token from the Dolibarr user account.
DOLIBARR_TIMEZONEOptional. Business timezone for Dolibarr date-only fields. Defaults to
Europe/Brussels.DOLIBARR_DEBUGOptional. Set to
trueto log Dolibarr requests and responses to the console.DOLIBARR_DEFAULT_WAREHOUSE_IDOptional. Default warehouse used when reopening validated customer invoices that may reverse stock movements.
DOLIBARR_DEFAULT_COMMERCIAL_IDOptional. Dolibarr user ID recorded as signing and follow-up representative on contracts created by
create_contract. Defaults to the API user.MCP_ALLOW_DELETESOptional. Set to
trueto enable guarded delete tools. Defaults to disabled.MCP_HTTP_HOSTDefaults to
0.0.0.0.MCP_HTTP_PORTDefaults to
3000.Run locally:
npm run devOr with Docker:
docker compose up
Related MCP server: FacturaHub MCP Server
Integration Tests
The integration tests run against a real Dolibarr REST API and create/delete real records. Use a development Dolibarr instance, not production data.
Required environment:
Variable | Description |
| Full Dolibarr REST API base URL. |
| API token with thirdparty, proposal, and product/service permissions. |
MCP_API_KEY is not used by these tests; if it is missing, the test runner sets a local dummy
value so the shared config module can load.
Run:
npm run test:integrationThe proposal test looks up the first available service through /products?mode=2&limit=1,
then creates a validated proposal with one catalog service line and one free-text line.
Dolibarr Requirements
The Dolibarr instance must have the API REST module enabled.
The Dolibarr API token belongs to a normal Dolibarr user, so that user's permissions decide what the MCP server can read or write. If a module is inactive or the user lacks rights, Dolibarr often returns a generic 403 Forbidden response.
Important Products/Services note:
Dolibarr exposes products and services through the same REST endpoint:
/productsThe MCP tools hide that detail:
Tool | Description |
| Searches only products. |
| Searches only services. |
However, even service searches use Dolibarr's /products API internally with mode=2.
That means the Products/Services module and API endpoint must be enabled, even if you only
use services and never create products.
For service search to work, confirm in Dolibarr:
API REST module is enabled.
Products/Services module is enabled.
The API user has read permission for products/services.
Implemented Tools
Read tools:
get_client_overviewget_invoice_detailget_supplier_invoice_detailget_proposal_detailget_monthly_revenueget_outstanding_receivablessearch_acrosssearch_document_contentsearch_productssearch_servicessearch_thirdpartieslist_invoiceslist_proposalslist_orderslist_contractslist_paymentslist_productslist_payment_modeslist_bank_accountslist_contracts_by_expiryget_contract_detaillist_interventionsget_maintenance_overviewlist_projectsget_project_detailget_pipeline_overviewlist_time_entries
Write tools:
create_thirdpartyupdate_thirdpartycreate_invoicecreate_credit_noteupdate_invoicecreate_supplier_invoiceupdate_supplier_invoicevalidate_invoicemark_invoice_paidcreate_proposalupdate_proposalvalidate_proposalset_proposal_statusupdate_productupdate_servicecreate_contractcreate_renewal_invoicecreate_interventionset_contract_statuscreate_projectupdate_projectset_project_statuscreate_taskupdate_tasklog_timeupdate_time_entrydelete_time_entry(guarded)delete_task(guarded)
See todo.md for the current implementation and verification checklist.
CRUD coverage
Entity | Create | Read | Update | Lifecycle / status | Delete |
Thirdparties |
|
|
| — | guarded |
Client invoices |
|
|
|
| guarded |
Supplier invoices |
|
|
|
| guarded |
Proposals |
|
|
|
| guarded |
Products / services | — |
|
| — | — |
Contracts |
|
| — |
| — |
Interventions |
|
| — | — | — |
Projects / leads |
|
|
|
| — |
Tasks |
|
|
| — | guarded |
Time entries |
|
|
| — | guarded |
Guarded delete tools require MCP_ALLOW_DELETES=true and confirm: true.
Browsing records and payments
All six list tools accept limit (1–100, default 50) and offset (default 0).
Responses include the named collection, count, has_more, and next_offset.
Lists use descending record ID order. Pagination reflects current data; concurrent
insertions or deletions can shift offsets between calls.
Tool | Optional filters |
|
|
|
|
|
|
|
|
|
|
|
|
Dates must be valid YYYY-MM-DD values and both endpoints are inclusive. Document
lists filter the document date; payments filter the payment date. Proposal sent
is an alias for validated because Dolibarr has no separate sent status. closed
includes accepted, refused and billed. Invoice cancelled corresponds to Dolibarr's
abandoned status; summaries use the existing abandoned label.
list_payments returns customer invoice payment allocations: one shared payment
can appear for multiple invoices, with each row's allocated amount. Supplier payments,
credit notes, discounts and deposit applications are excluded. The bundled Dolibarr
API exposes payments per invoice, so the tool scans invoices of all dates (up to
max_invoices, default 1000, maximum 10000) with bounded concurrency, then sorts
allocations by payment date descending within that scan. A recent payment on an old
invoice can therefore be found. scan.complete is true only when the scan includes
all invoices from offset zero. If scan.more_invoices_available is true, resume at
scan.next_invoice_offset. First paginate allocations in the current scan using
next_offset; reset offset to zero when advancing invoice_offset. An empty payment
page with an incomplete invoice scan does not establish that no payments exist.
search_document_content accepts thirdparty_id and thirdparty_name. A name is
resolved before listing documents; ambiguous names return candidates and missing
names return a structured error. Supplying both filters requires them to identify
the same thirdparty. The customer filter applies before the recent-document
scan limit for every document type. The scan remains bounded, with the existing
per-type more_documents_available metadata indicating older documents may remain.
Example calls:
{"name":"list_invoices","arguments":{"thirdparty_id":7,"status":"paid","limit":25}}
{"name":"search_document_content","arguments":{"query":"maintenance","thirdparty_name":"Example Company"}}Updating documents
update_invoice, update_supplier_invoice, and update_proposal change header fields and
lines of a draft document in one call:
update_linesedits existing lines byline_id(from the detail tools). Fields left out keep their current value.add_linesappends lines in the same shape as the create tools'lines.remove_line_idsdeletes lines.
All inputs are checked before the first write, so a rejected request leaves the document
unchanged. Non-draft documents are refused with NOT_DRAFT; reopen them with the matching
set_*_status tool (status: "draft") first. Dolibarr's REST API itself accepts header
changes on validated documents, so this restriction is enforced by the MCP server.
Status changes are not updates: validation, acceptance/refusal, payments, and reopening stay in their explicit lifecycle tools.
update_proposal keeps the validity period when only the date changes, so the end date
moves with it. Pass valid_until to set the end date explicitly.
create_invoice and update_invoice take an optional due_date, which must not be before
the invoice date. Without it, create_invoice lets Dolibarr derive the due date from the
payment terms. When update_invoice changes only the date, it recomputes the due date from
the payment terms, as the Dolibarr UI does. The REST API alone would keep the old due date.
create_invoice takes type (standard, the default, or deposit for a voorschotfactuur /
facture d'acompte) and an optional proposal (ref or ID). The proposal must belong to the same
client. The invoice is linked to it on creation, and the response's linked_to_proposal confirms
that Dolibarr stored the link. get_invoice_detail returns the invoice type and
linked_proposal_ids. Deducting a deposit from the final invoice is not supported yet.
create_credit_note credits a validated or paid client invoice and takes the client from it.
mode: "full" copies every invoice line; mode: "partial" takes the lines to credit as
positive quantities and prices, because Dolibarr makes the amounts negative itself. It refuses
to credit more than the invoice total minus earlier credit notes (CREDIT_EXCEEDS_INVOICE), and
full is refused once a credit note exists. reason is stored as a private note. The response
reports whether the invoice is paid and what remains to pay, and linked_to_invoice confirms
that Dolibarr stored the link. The tool does not refund the money or apply the credit to the
invoice; do that in Dolibarr.
Updating products and services
update_product and update_service change the ref, label, description, selling price
(excl. tax), VAT rate, on sale / on purchase flags, and notes of a catalog item found by exact
ref or ID. Only the fields you pass change. The item type is never changed: using
update_service on a product (or the reverse) returns CATALOG_TYPE_MISMATCH, and a ref
that is already taken returns DUPLICATE_REF.
Dolibarr applies price and VAT changes through this API only in "one price per product" or
customer-price mode. In per-segment or per-quantity pricing it drops them silently, so the
tools re-read the item and return a warnings entry when the price or VAT rate did not change.
The API user needs create/modify rights on products/services.
Maintenance contracts
The maintenance tools answer which contracts expire or have expired, whether a renewal invoice
exists, and which visits were carried out. They use only the REST API and delete nothing; the
write tools are plain create/status tools, so the MCP client's tool approval is the confirmation
step, as for the other create_* tools. All of them work on the Dolibarr instance configured in
DOLIBARR_URL.
Rules the tools derive (Dolibarr keeps none of them on the contract itself):
End date: a contract has no end date of its own. It is the latest
date_endover its lines. A line with status 4 (running) and an end date before today is expired.Status (
expired|expiring|running):expiredwhen the end date is before today,expiringwithindays_aheaddays,runningotherwise.list_contracts_by_expiryonly lists contracts with at least one running line and an end date; drafts, fully closed contracts and contracts without any line end date have nothing to expire.renewal_invoiced: true when a linked invoice is dated more than 30 days after the contract start (date_contrat, else the earliest line start). Abandoned invoices do not count. Dolibarr's list endpoint carries no linked objects, so each listed contract is re-read throughGET /contracts/{id}.Yearly value excl. VAT: the line totals of all lines that are not closed, scaled to 12 months when a line covers another period.
create_contract creates the contract, adds the service lines, validates it and activates every
line, for duration_months from start_date (12 months from 2026-01-01 ends 2026-12-31).
Dolibarr requires a signing and follow-up representative, so it uses
DOLIBARR_DEFAULT_COMMERCIAL_ID or else the API user (/users/info); when neither is
available it returns a VALIDATION_ERROR that names the variable.
create_renewal_invoice bills the period after the contract's current end date, as long as the
contract term (or period_months), with the period in each line description and as the line's
service dates. The invoice is linked through linked_objects: {"contrat": id}, the only way
Dolibarr accepts; the tool re-reads the contract to confirm the link. It refuses with
RENEWAL_ALREADY_INVOICED when a renewal invoice is already linked, unless allow_duplicate
is set. It does not change the contract's own line dates, so the contract keeps showing as
expired or expiring until its lines are extended in Dolibarr.
create_intervention creates an intervention on the contract's client (fk_project 0,
fk_contrat set), adds one line with the date and duration, validates it and, unless
close: false, marks it done (status 3). get_maintenance_overview reports the latest done
intervention per contract and flags contracts with running services and no done intervention in
the last 12 months.
set_contract_status closes a contract (closed) or deactivates lines (lines_deactivated).
In Dolibarr both end up as closed service lines (status 5); nothing is deleted. Closing a draft
contract is refused, because Dolibarr would validate it as a side effect.
If a later step of a create tool fails, the record created so far is kept and the error carries
its ID (contract_id, invoice_id, intervention_id) plus the failed step.
Projects, leads, tasks and time
Dolibarr has no separate lead object: a lead is a project with "follow an opportunity"
(usage_opportunity) set, plus a stage, an amount and a probability. The project tools
handle both kinds of project, and every project belongs to an existing thirdparty.
Projects are addressed by Dolibarr ID, exact ref (
PJ2511-0004) or title. A title matches on a substring; one exact title wins over partial matches, and several matches returnPROJECT_AMBIGUOUSwith candidates.Lead stages are the default Dolibarr dictionary (
llx_c_lead_status), which the REST API does not expose:prospection(0%),qualification(20%),proposal(40%),negotiation(60%),pending(50%, inactive by default),won(100%),lost(0%). Setting a stage without a probability uses the stage's percentage. Weighted amount = amount × probability. If the dictionary has been changed in Dolibarr, the IDs insrc/dolibarr/projects/projectRules.tsmust be changed to match.Pipeline:
get_pipeline_overviewcounts leads that are not closed and not won or lost. It totals them per stage and lists leads whose end date (expected close) has passed. Marking a lead won or lost does not close the project and creates nothing else; useset_project_statusfor that.create_projectcreates the project with refautoand makes the API user project leader, as the Dolibarr UI does (the REST API does not). The API user is read from/users/info, falling back toDOLIBARR_DEFAULT_COMMERCIAL_ID. If that step fails, the response carries a warning instead of failing, because a project visible only to assigned contacts would be hidden from users who cannot see all projects. By default the project is then validated (open).set_project_status:openvalidates a draft or reopens a closed project (POST /projects/{id}/validate, the same call the UI uses to reopen). Dolibarr has no close endpoint, soclosedsetsstatus: 2,date_closeandfk_user_closethroughPUT /projects/{id}. That skips thePROJECT_CLOSEtrigger.Tasks are created through
POST /tasks; Dolibarr'sPOST /projects/{id}/tasksroute is commented out. A task is billable when its project bills time.update_taskwithprogress: 100marks it done.log_timefinds the task by ref or ID, or by project plus task label. With only a project it uses that project's single task, and returnsTASK_AMBIGUOUSwith the task list when there are several. The entry starts atstart_time(default 09:00) inDOLIBARR_TIMEZONEand is sent to Dolibarr in GMT. Dolibarr returns no ID for the new entry, so the response shows the task's spent hours before and after.list_time_entriesreadsGET /projects/alltimespent. That endpoint'sthirdparty_idsparameter filters on a column tasks do not have, so the client filter goes throughsqlfilterson the project (p.fk_soc). It scans at most 1000 entries and warns when it hits that limit.update_time_entrycorrects one entry by its ID (shown bylist_time_entries): hours, date, start time, note or user. Dolibarr overwrites every field of the entry from the request, so the tool resends the current value of each field you leave out. Moving the date keeps the start time. Time that is already on an invoice is refused (TIME_ENTRY_INVOICED).delete_time_entrydeletes one entry. Withoutconfirm: trueit is a dry run that shows the entry. Invoiced time is refused. After deleting, the tool checks that the entry is really gone.delete_taskis refused for a task with subtasks (TASK_HAS_SUBTASKS). Dolibarr also refuses a task with time logged, so the tool returnsTASK_HAS_TIMEunless you passdelete_time_entries: true. It then deletes those entries first, but checks all of them before deleting anything: one invoiced entry stops the whole delete. The dry run shows the number of subtasks, time entries and hours. Both delete tools needMCP_ALLOW_DELETES=true, like the other guarded deletes.get_project_detaillists the proposals, orders, client invoices and supplier invoices that havefk_projetset to the project. Its totals count signed (accepted or billed) proposals, and validated or paid invoices. A module the API user cannot read contributes nothing instead of failing the call.
Marking invoices paid
mark_invoice_paid handles both client and supplier invoices. The invoice must already be
validated. With no payment input it only marks the invoice paid. With
payment.mode: "create", it creates a payment for the remaining balance and asks Dolibarr to
close the invoice in the same transaction. payment_mode accepts an ID, exact code, or unique
label; bank_account accepts an ID, exact ref, or unique label/bank name. Use
list_payment_modes and list_bank_accounts to inspect the available choices. Numeric
payment_mode_id and account_id remain supported for compatibility.
Before creating the payment, the tool resolves both selections against Dolibarr. Its response includes the resolved payment mode and bank account names, refs, and masked account identifier, so callers can confirm where the payment was recorded.
Dolibarr's invoice REST APIs can list payments already allocated to an invoice, but cannot add
a new allocation for a previously created payment. payment.mode: "existing" therefore
verifies that the supplied payment reference or number is already linked before marking the
invoice paid. Link an unallocated existing payment in the Dolibarr UI first.
Project Structure
The MCP tool files are intentionally thin: they define the Zod input schema, call a domain service or Dolibarr API module, and format the MCP response.
Tools are grouped by business domain under src/tools/:
cataloginvoicespaymentsprojectsproposalssearchthirdparties
Shared document creation logic lives in:
src/dolibarr/documents/documentCreationService.tsThat service handles the common workflow for invoices, supplier invoices, and proposals: resolve the thirdparty, resolve catalog/free-text lines, create the document, add lines, and optionally validate it.
Draft document updates use the matching src/dolibarr/documents/documentUpdateService.ts,
which enforces the draft-only rule, validates line IDs and new lines up front, and merges
line edits with the existing line before sending them to Dolibarr.
Errors
Tool errors are returned as structured JSON. For example, when Dolibarr returns a 403 for a known module endpoint, the server returns:
{
"error": "DOLIBARR_MODULE_UNAVAILABLE",
"message": "Dolibarr refused access to the ... API. The module may be inactive or the API user may be missing permissions.",
"action": "..."
}Because Dolibarr uses the same 403 shape for inactive modules and missing permissions, check both when debugging access failures.
License
Copyright (c) 2026 Gert Vermeersch.
This project is licensed under the MIT License.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Query your books, company data, business health, and ship invoices from your AI assistant.
The whole back office for your AI agent: CRM, invoices, books, email and more. Pay per action.
Run your service firm from your AI: client work to review, clients, deliverables, invoices.
Run a service business from your AI agent: CRM, leads, scheduling, invoicing, jobs and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables comprehensive interaction with ERPNext systems through natural language, providing secure access to any document type (customers, items, invoices, etc.) with enterprise-grade permission controls and audit logging.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage business operations including invoicing, WooCommerce syncing, expense tracking, POS, inventory, and team management through natural language.12 npm2MIT
- AlicenseAqualityCmaintenanceLets an AI assistant read and write business records in plain language, including looking up people, creating and updating tasks, logging time, and pulling utilization reports through a synthetic ops platform or an optional ClickUp adapter.8MIT
- AlicenseAqualityCmaintenanceEnables AI agents to browse customers, bookings, and availability while any booking creation or cancellation stays gated behind a human-approved, single-use token cryptographically bound to the exact arguments. Runs over stdio or Streamable HTTP and enforces the read/write separation in host code with a full audit trail.7MIT