Skip to main content
Glama
Dolibarr MCP Server

Dolibarr MCP Server

Dolibarr MCP Server

CI License: MIT

A Model Context Protocol (MCP) server for Dolibarr ERP & CRM. It lets AI assistants such as Claude look up and work with the data in a Dolibarr instance — third parties, products, proposals, orders, shipments, invoices, purchasing, stock, manufacturing, projects, tickets and the agenda — through Dolibarr's standard REST API.

The server works with an unmodified Dolibarr installation. It keeps no business data of its own: every call is made with the connected user's own Dolibarr API key, so Dolibarr's permissions apply exactly as they do in the web interface.

Features

  • 92 tools across 11 toolsets, covering the standard Dolibarr modules. Enable only the toolsets you need.

  • Safe by design. Creating and editing drafts happens directly. Steps that cannot simply be undone — validating, approving, closing, deleting, stock movements, payments — are guarded: they return a preview first and only run when called again with explicit confirmation and a reason.

  • Read-only mode, per instance or per connection.

  • Two ways to run:

    • stdio — a local process for one user, for Claude Desktop, Claude Code and other MCP clients.

    • HTTP — a remote server for a team, with OAuth 2.1 sign-in. Each person signs in with their own Dolibarr login; long-lived tokens are available for automated agents. Every tool call is written to an audit log.

  • Agent-friendly replies. Responses are compacted (empty and internal fields removed, timestamps turned into dates, status codes into labels) and Dolibarr errors are explained in plain words with a hint on what to do next.

  • Generic fallback. For anything not covered by a dedicated tool, the agent can search the instance's own API catalogue and call any endpoint.

  • Workflow prompts for common tasks, such as preparing a quote, shipping and invoicing an order, or listing unpaid invoices.

Related MCP server: MCP Server for Odoo

Requirements

  • Dolibarr with the API REST module enabled. The server is developed and tested against Dolibarr 22.0; earlier versions with the REST API are likely to work for most tools but are not tested.

  • Node.js 22.13 or later.

  • A Dolibarr API key for each user (on the user card, API key field). In HTTP mode, a user who may edit their own user record gets a key automatically at first sign-in.

Quick start (local, stdio)

git clone https://github.com/frankiewonghk/dolibarr-mcp-server.git
cd dolibarr-mcp-server
npm ci
npm run build

Then add the server to your MCP client.

Claude Desktop — edit claude_desktop_config.json:

{
  "mcpServers": {
    "dolibarr": {
      "command": "node",
      "args": [
        "--disable-warning=ExperimentalWarning",
        "/absolute/path/to/dolibarr-mcp-server/dist/index.js",
        "stdio"
      ],
      "env": {
        "DOLIBARR_URL": "https://erp.example.com",
        "DOLIBARR_API_KEY": "your-dolibarr-api-key"
      }
    }
  }
}

Claude Code:

claude mcp add dolibarr --env DOLIBARR_URL=https://erp.example.com --env DOLIBARR_API_KEY=your-dolibarr-api-key -- node /absolute/path/to/dolibarr-mcp-server/dist/index.js stdio

Restart the client and ask, for example, "Which customer invoices are overdue?" The agent starts with dolibarr_whoami to confirm the connection.

DOLIBARR_URL is the address of the Dolibarr site, without /api/index.php.

Remote server (HTTP with OAuth)

In HTTP mode the server is shared by a team. Users connect from their MCP client (for example Claude → Settings → Connectors → Add custom connector, URL https://mcp.example.com/mcp), sign in on the server's sign-in page with their Dolibarr login and password, and choose whether to allow changes or look-ups only.

  • The password is checked by Dolibarr (POST /api/index.php/login) and is never stored. The user's Dolibarr API key stays on the server, encrypted with AES-256-GCM.

  • Clients receive short-lived access tokens (default 1 hour), renewed automatically with rotating refresh tokens (default 30 days).

  • Tokens are stored only as SHA-256 hashes; a copy of the database file alone gives no access.

  • Repeated failed sign-ins are rate-limited per login and per address.

Minimal configuration:

DOLIBARR_URL=https://erp.example.com
MCP_PUBLIC_URL=https://mcp.example.com
MCP_SECRET_KEY=$(openssl rand -hex 32)
npm start -- http

The server listens on 127.0.0.1:3900 and must be published over HTTPS through a reverse proxy. See docs/deployment.md for a complete production setup (systemd, nginx or Apache, Docker) and docs/administration.md for managing tokens and the audit log.

Configuration

All settings are environment variables. In local use they can also be placed in a .env file (see .env.example).

Variable

Default

Description

DOLIBARR_URL

—

Required. Dolibarr site URL, without /api/index.php.

DOLIBARR_API_KEY

—

stdio mode: API key of the user the server acts as.

DOLIBARR_NAME

Dolibarr

Display name of the instance, shown to the agent and on the sign-in page.

DOLIBARR_TOOLSETS

all

all, or a comma-separated list of toolsets (see below). core is always on.

DOLIBARR_WRITE_MODE

guarded

guarded: write tools available, irreversible steps need confirmation. off: read-only for everyone.

DOLIBARR_TIMEOUT_MS

30000

Timeout of each Dolibarr API call.

MCP_HOST

127.0.0.1

HTTP mode: listen address.

MCP_PORT

3900

HTTP mode: listen port.

MCP_PUBLIC_URL

—

HTTP mode, required: public HTTPS address of this server, e.g. https://mcp.example.com.

MCP_SECRET_KEY

—

HTTP mode, required: 64 hex characters (openssl rand -hex 32). Encrypts stored API keys; changing it invalidates every sign-in and token.

MCP_DB_PATH

./data/dolibarr-mcp.sqlite

HTTP mode: SQLite file for clients, tokens and the audit log.

MCP_ALLOWED_HOSTS

localhost,127.0.0.1

HTTP mode: accepted Host headers, in addition to the public host name.

MCP_TRUST_PROXY

loopback

HTTP mode: which proxies may set X-Forwarded-For (Express syntax).

MCP_ACCESS_TTL_MIN

60

Lifetime of access tokens, in minutes.

MCP_REFRESH_TTL_DAYS

30

Lifetime of refresh tokens, in days.

MCP_AUDIT_KEEP_DAYS

365

Days of audit log to keep.

Toolsets and tools

Search tools take free text and filters and return ids and refs; get tools take an id or a ref. Bold tools are guarded (preview first, then confirm: true with a reason). Write tools are not offered at all on a read-only connection.

Toolset

Dolibarr modules

Tools

core

API

dolibarr_whoami, dolibarr_custom_field_list, dolibarr_dictionary, dolibarr_api_find_endpoint, dolibarr_api_get, dolibarr_api_write

thirdparties

Third parties

dolibarr_thirdparty_search, _get, _create, _update; dolibarr_contact_search, _get, _create, _update

products

Products, Services

dolibarr_product_search, _get, _create, _update

sales

Commercial proposals, Sales orders, Shipments

dolibarr_proposal_search, _get, _create, _update, _line, _action; dolibarr_order_search, _get, _create, _create_from_proposal, _update, _line, _action; dolibarr_shipment_search, _get, _create, _action

invoices

Customer invoices

dolibarr_invoice_search, _get, _create, _create_from_order, _update, _line, _action, _record_payment

purchasing

Supplier orders, Receptions, Supplier invoices

dolibarr_supplier_order_search, _get, _create, _update, _action, _receive; dolibarr_reception_search, _get, _create, _action; dolibarr_supplier_invoice_search, _get, _create, _line, _action, _record_payment

stock

Stock

dolibarr_warehouse_list, dolibarr_product_stock, dolibarr_stock_movement_search, dolibarr_stock_correct, dolibarr_stock_transfer

production

BOM, Manufacturing orders

dolibarr_bom_search, _get, _create, _line, _delete; dolibarr_mo_search, _get, _create, _delete, _produce

projects

Projects

dolibarr_project_search, _get, _create, _update, _action; dolibarr_task_get, _create, _update, _add_time

tickets

Tickets

dolibarr_ticket_search, _get, _create, _update, _add_message

agenda

Agenda

dolibarr_event_search, _get, _create, _update

The *_action tools move a document through its life cycle, for example:

Tool

Actions

dolibarr_proposal_action

validate, set_draft, sign, refuse, set_billed, delete

dolibarr_order_action

validate, set_draft, close, reopen, set_billed, delete

dolibarr_shipment_action

validate, close, delete

dolibarr_invoice_action

validate, set_draft, set_paid, set_unpaid, delete

dolibarr_supplier_order_action

validate, approve, mark_ordered, delete

dolibarr_reception_action

validate, close, delete

dolibarr_supplier_invoice_action

validate, set_draft, delete

dolibarr_project_action

validate, delete

Workflow prompts

The server also offers prompts that guide the agent through common tasks. A read-only connection receives only the read prompts.

Prompt

Purpose

customer_overview

Open proposals, orders, unpaid invoices and recent activity of a customer

order_status

Where a sales order stands: lines, shipments, invoicing

stock_check

Stock of a product per warehouse and lot, with recent movements

unpaid_invoices

Unpaid customer invoices, oldest first, with what is overdue

new_quote

Prepare and validate a commercial proposal

new_sales_order

Enter and validate a sales order

ship_and_invoice

Ship a validated order and invoice it

purchase_and_receive

Order from a supplier, take the order through approval, receive the goods

log_time

Record time spent on a project task

How changes are kept safe

  • Every call runs as the connected Dolibarr user. A refusal for missing rights (HTTP 403) is reported to the user and never worked around.

  • A read-only connection (read token, or DOLIBARR_WRITE_MODE=off) does not receive the write tools at all.

  • Creating and editing drafts is not guarded: a draft moves no stock, has no accounting effect and can be deleted.

  • Guarded tools carry the MCP destructiveHint annotation, so clients ask the user before running them. Called without confirm: true, they change nothing and return a preview of the record and the effect of the step. With confirm: true they also require a reason, which is kept in the audit log in HTTP mode.

  • Line updates send the complete line back to Dolibarr, so fields that were not meant to change are not reset.

  • Replies longer than 60,000 characters are cut, with a note asking the agent to narrow the request.

Limitations of the standard API

Some operations are not available through Dolibarr's standard REST API and therefore not through this server:

  • Bills of materials and manufacturing orders cannot be validated through the API. Validate them in the web interface; production can then be posted with dolibarr_mo_produce.

  • Lot- and serial-tracked products cannot be shipped (dolibarr_shipment_create) or consumed and produced (dolibarr_mo_produce) through the API. Receiving them with a lot number is supported.

  • Supplier order lines cannot be edited after creation; delete the draft and create it again.

  • PDF documents are not generated by these tools; use the web interface or dolibarr_api_find_endpoint with the documents routes.

Anything else the API offers can be reached with dolibarr_api_get and, as a guarded last resort, dolibarr_api_write.

Development

npm ci
npm run dev -- stdio    # run from source (reads .env)
npm test                # unit and integration tests
npm run typecheck
npm run build

Project layout:

src/index.ts            entry point: stdio, http, or an admin command
src/server.ts           builds the MCP server and registers the enabled toolsets
src/config.ts           environment parsing
src/instructions.ts     guidance sent to the agent on connection
src/prompts.ts          workflow prompts
src/http.ts             HTTP mode: OAuth endpoints, sign-in page, /mcp endpoint
src/cli.ts              admin commands (tokens, audit log)
src/auth/               OAuth provider, token store, encryption, rate limiting
src/dolibarr/           REST client, transport, sign-in, response shaping
src/tools/              one file per toolset, plus shared helpers
test/                   vitest suites
deploy/                 systemd unit, reverse proxy examples, admin wrapper

To add a tool, register it in the matching file under src/tools/ with readTool (look-ups) or writeTool (changes; pass guarded: true for steps that cannot simply be undone and supply a preview), name it dolibarr_<area>_<verb>, and return shaped data rather than raw API objects.

Contributing

Issues and pull requests are welcome. Please run npm run typecheck and npm test before submitting, and see CONTRIBUTING.md. To report a security issue, follow SECURITY.md.

License

MIT. Dolibarr is a trademark of its respective owners; this project is an independent integration and is not affiliated with or endorsed by the Dolibarr project.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Odoo ERP systems through natural language to search records, create entries, update data, and manage business operations. Supports secure authentication and configurable access controls for production environments.
      Mozilla Public 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with Odoo ERP systems through natural language, allowing users to search, create, update, and manage business records like customers, products, and invoices across any Odoo instance.
      1
      Mozilla Public 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a Model Context Protocol interface for the Dolibarr ERP/CRM, enabling AI agents to manage customers, products, invoices, and orders. It features specialized search tools and server-side filtering to efficiently interact with Dolibarr's REST API while minimizing token usage.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to natively interact with Dolibarr ERP/CRM through its REST API, providing over 30 tools for managing customers, contacts, products, quotes, orders, invoices, stock, projects, contracts, interventions, and PDF generation, while supporting complex workflow orchestration and read-only security modes.
      MIT