MokoConsulting/mcp-mokocrm-api
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: merge dev into main � MCP underscore convention + new features #1

Merged
jmiller merged 5 commits from dev into main 2026-05-19 19:59:30 +00:00
Conversation 0 Commits 5 Files Changed 5
+1 -1061
5 changed files with 1 additions and 1061 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API.md
-753
View File
@@ -1,753 +0,0 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: dolibarr-api-mcp.Documentation
INGROUP: dolibarr-api-mcp
REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
PATH: /docs/API.md
VERSION: 01.00.00
BRIEF: MCP tool reference documentation
-->
# API Reference
All tools accept an optional `connection` parameter to target a specific named connection. If omitted, the default connection is used.
All list tools accept optional pagination parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | number | Max results (default 100) |
| `page` | number | Page number (0-based) |
| `sortfield` | string | Field to sort by |
| `sortorder` | `"ASC"` / `"DESC"` | Sort direction |
## Third Parties
### `dolibarr_thirdparties_list`
List third parties (customers, suppliers, prospects).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | `"1"` / `"2"` / `"3"` / `"4"` | No | 1=customer, 2=prospect, 3=supplier, 4=customer+supplier |
| `search` | string | No | Search in name |
| `category` | number | No | Filter by category ID |
### `dolibarr_thirdparty_get`
Get a single third party by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Third party ID |
### `dolibarr_thirdparty_create`
Create a new third party.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Company or individual name |
| `client` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=neither, 1=customer, 2=prospect, 3=customer+prospect |
| `fournisseur` | `"0"` / `"1"` | No | 0=not supplier, 1=supplier |
| `email` | string | No | Email address |
| `phone` | string | No | Phone number |
| `address` | string | No | Street address |
| `zip` | string | No | Postal code |
| `town` | string | No | City |
| `country_id` | number | No | Country ID |
### `dolibarr_thirdparty_update`
Update an existing third party. Only provided fields are changed.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Third party ID |
| `name` | string | No | Company or individual name |
| `email` | string | No | Email address |
| `phone` | string | No | Phone number |
| `address` | string | No | Street address |
| `zip` | string | No | Postal code |
| `town` | string | No | City |
| `country_id` | number | No | Country ID |
### `dolibarr_thirdparty_delete`
Delete a third party.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Third party ID |
## Invoices
### `dolibarr_invoices_list`
List invoices.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"draft"` / `"unpaid"` / `"paid"` / `"cancelled"` | No | Filter by status |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
| `search` | string | No | Search in ref or ref_client |
### `dolibarr_invoice_get`
Get a single invoice by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
### `dolibarr_invoice_create`
Create a new invoice.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `type` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=standard, 1=replacement, 2=credit note, 3=deposit |
| `date` | string | No | Invoice date (YYYY-MM-DD or Unix timestamp) |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |
### `dolibarr_invoice_add_line`
Add a line item to an invoice.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
| `desc` | string | Yes | Line description |
| `subprice` | number | Yes | Unit price (HT) |
| `qty` | number | Yes | Quantity |
| `tva_tx` | number | No | VAT rate (e.g. 20.0) |
| `product_id` | number | No | Product/service ID |
### `dolibarr_invoice_validate`
Validate (finalize) a draft invoice. Changes status from draft to validated and assigns an invoice number.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
### `dolibarr_invoice_set_paid`
Mark an invoice as paid.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
| `close_code` | string | No | Close code (e.g. `"bankorder"`, `"cash"`) |
| `close_note` | string | No | Close note |
## Proposals (Quotes)
### `dolibarr_proposals_list`
List commercial proposals.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` / `"3"` / `"4"` | No | 0=draft, 1=validated, 2=signed, 3=not-signed, 4=billed |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
### `dolibarr_proposal_get`
Get a single proposal by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |
### `dolibarr_proposal_create`
Create a new commercial proposal.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `date` | string | No | Proposal date (YYYY-MM-DD or Unix timestamp) |
| `duree_validite` | number | No | Validity duration in days |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |
### `dolibarr_proposal_add_line`
Add a line item to a proposal.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |
| `desc` | string | Yes | Line description |
| `subprice` | number | Yes | Unit price (HT) |
| `qty` | number | Yes | Quantity |
| `tva_tx` | number | No | VAT rate (e.g. 20.0) |
| `product_id` | number | No | Product/service ID |
### `dolibarr_proposal_validate`
Validate a draft proposal.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |
### `dolibarr_proposal_close`
Close a proposal (sign or refuse).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |
| `status` | `"2"` / `"3"` | Yes | 2=signed, 3=not signed (refused) |
| `note` | string | No | Close note |
## Orders
### `dolibarr_orders_list`
List customer orders.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` / `"3"` / `"-1"` | No | 0=draft, 1=validated, 2=processing, 3=delivered, -1=cancelled |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
### `dolibarr_order_get`
Get a single order by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Order ID |
### `dolibarr_order_create`
Create a new customer order.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `date` | string | No | Order date (YYYY-MM-DD or Unix timestamp) |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |
### `dolibarr_order_validate`
Validate a draft order.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Order ID |
## Products / Services
### `dolibarr_products_list`
List products and/or services.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | `"0"` / `"1"` | No | 0=product, 1=service |
| `search` | string | No | Search in label or ref |
| `category` | number | No | Filter by category ID |
| `to_sell` | `"0"` / `"1"` | No | 1=for sale only |
| `to_buy` | `"0"` / `"1"` | No | 1=for purchase only |
### `dolibarr_product_get`
Get a single product/service by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Product ID |
### `dolibarr_product_create`
Create a new product or service.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ref` | string | Yes | Product reference code |
| `label` | string | Yes | Product label/name |
| `type` | `"0"` / `"1"` | No | 0=product, 1=service (default 0) |
| `price` | number | No | Selling price (HT) |
| `price_ttc` | number | No | Selling price (TTC) |
| `tva_tx` | number | No | Default VAT rate |
| `description` | string | No | Description |
| `status` | `"0"` / `"1"` | No | 1=on sale, 0=not on sale |
| `status_buy` | `"0"` / `"1"` | No | 1=on purchase, 0=not on purchase |
### `dolibarr_product_update`
Update a product or service. Only provided fields are changed.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Product ID |
| `ref` | string | No | Product reference code |
| `label` | string | No | Product label/name |
| `price` | number | No | Selling price (HT) |
| `description` | string | No | Description |
| `status` | `"0"` / `"1"` | No | On sale flag |
| `status_buy` | `"0"` / `"1"` | No | On purchase flag |
### `dolibarr_product_stock`
Get stock levels for a product across all warehouses.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Product ID |
## Contacts / Addresses
### `dolibarr_contacts_list`
List contacts/addresses.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search in name |
| `thirdparty_id` | number | No | Filter by third party ID |
### `dolibarr_contact_get`
Get a single contact by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Contact ID |
## Projects
### `dolibarr_projects_list`
List projects.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=open, 2=closed |
| `search` | string | No | Search in title or ref |
### `dolibarr_project_get`
Get a single project by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Project ID |
### `dolibarr_project_create`
Create a new project.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ref` | string | Yes | Project reference |
| `title` | string | Yes | Project title |
| `socid` | number | No | Third party ID |
| `description` | string | No | Project description |
| `date_start` | string | No | Start date (YYYY-MM-DD or Unix timestamp) |
| `date_end` | string | No | End date (YYYY-MM-DD or Unix timestamp) |
## Tasks
### `dolibarr_tasks_list`
List project tasks.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | number | No | Filter by project ID |
### `dolibarr_task_get`
Get a single task by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Task ID |
## Users
### `dolibarr_users_list`
List Dolibarr users.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search in login name |
### `dolibarr_user_get`
Get a single user by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | User ID |
## Categories
### `dolibarr_categories_list`
List categories.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | `"product"` / `"supplier"` / `"customer"` / `"member"` / `"contact"` / `"project"` | No | Category type |
| `search` | string | No | Search in label |
## Bank Accounts
### `dolibarr_bankaccounts_list`
List bank accounts. No additional parameters (supports pagination).
## Supplier Invoices
### `dolibarr_supplier_invoices_list`
List supplier invoices.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"draft"` / `"unpaid"` / `"paid"` / `"cancelled"` | No | Filter by status |
| `thirdparty_ids` | string | No | Comma-separated supplier IDs |
## Supplier Orders
### `dolibarr_supplier_orders_list`
List supplier orders (purchase orders).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` - `"5"`, `"9"` | No | 0=draft, 1=validated, 2=approved, 3=ordered, 4=partially received, 5=received, 9=cancelled |
| `thirdparty_ids` | string | No | Comma-separated supplier IDs |
## Shipments
### `dolibarr_shipments_list`
List shipments (expeditions).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=validated, 2=closed |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
### `dolibarr_shipment_get`
Get a single shipment by ID.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Shipment ID |
### `dolibarr_shipment_create`
Create a new shipment.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `origin_id` | number | No | Source order ID |
| `origin_type` | string | No | Source type (e.g. `"commande"`) |
| `date_delivery` | string | No | Delivery date |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |
### `dolibarr_shipment_validate`
Validate a draft shipment.
### `dolibarr_shipment_close`
Close a shipment (mark as delivered).
## Contracts / Subscriptions
### `dolibarr_contracts_list`
List contracts/subscriptions.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"4"` / `"5"` | No | 0=draft, 1=validated, 4=closed, 5=running |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
### `dolibarr_contract_get`
Get a single contract by ID.
### `dolibarr_contract_create`
Create a new contract.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party ID |
| `ref` | string | No | Contract reference |
| `date_contrat` | string | No | Contract date |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |
### `dolibarr_contract_validate`
Validate a draft contract.
## Interventions
### `dolibarr_interventions_list`
List interventions (field service).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=validated, 2=billed |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
### `dolibarr_intervention_get`
Get a single intervention by ID.
## Expense Reports
### `dolibarr_expensereports_list`
List expense reports.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"2"` / `"4"` / `"5"` / `"6"` / `"99"` | No | 0=draft, 2=validated, 4=cancelled, 5=approved, 6=paid, 99=refused |
### `dolibarr_expensereport_get`
Get a single expense report by ID.
### `dolibarr_expensereport_create`
Create a new expense report.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fk_user_author` | number | Yes | User ID of the author |
| `date_debut` | string | Yes | Start date |
| `date_fin` | string | Yes | End date |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |
## Tickets (Helpdesk)
### `dolibarr_tickets_list`
List helpdesk tickets.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status |
| `search` | string | No | Search in subject |
### `dolibarr_ticket_get`
Get a single ticket by ID.
### `dolibarr_ticket_create`
Create a new helpdesk ticket.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `subject` | string | Yes | Ticket subject |
| `message` | string | Yes | Ticket message/description |
| `type_code` | string | No | Ticket type code |
| `category_code` | string | No | Ticket category code |
| `severity_code` | string | No | Ticket severity code |
| `socid` | number | No | Third party ID |
| `notify_tiers_at_create` | number | No | 1=notify third party on creation |
## Agenda / Events
### `dolibarr_agendaevents_list`
List agenda events.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | No | Event type code |
| `status` | `"-1"` / `"0"` / `"50"` / `"100"` | No | -1=cancelled, 0=draft, 50=in progress, 100=done |
| `userassigned` | number | No | Filter by assigned user ID |
### `dolibarr_agendaevent_get`
Get a single agenda event by ID.
### `dolibarr_agendaevent_create`
Create a new agenda event.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | Yes | Event label/title |
| `type_code` | string | Yes | Event type code (e.g. `"AC_RDV"`, `"AC_TEL"`, `"AC_OTH"`) |
| `datep` | string | Yes | Start date (YYYY-MM-DD HH:MM:SS or Unix timestamp) |
| `datef` | string | No | End date |
| `socid` | number | No | Third party ID |
| `contactid` | number | No | Contact ID |
| `fk_project` | number | No | Project ID |
| `userownerid` | number | No | Owner user ID |
| `note` | string | No | Event note |
| `percentage` | `"-1"` / `"0"` / `"50"` / `"100"` | No | Completion status |
### `dolibarr_agendaevent_update`
Update an agenda event.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Event ID |
| `label` | string | No | Event label |
| `datep` | string | No | Start date |
| `datef` | string | No | End date |
| `percentage` | `"-1"` / `"0"` / `"50"` / `"100"` | No | Completion status |
| `note` | string | No | Event note |
## Payments
### `dolibarr_invoice_payments`
List payments for an invoice.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
### `dolibarr_invoice_add_payment`
Add a payment to an invoice.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
| `datepaye` | string | Yes | Payment date |
| `paymentid` | number | Yes | Payment type ID (e.g. 4=bank transfer, 6=credit card) |
| `closepaidinvoices` | string | No | `"yes"` to auto-close fully paid invoices |
| `accountid` | number | No | Bank account ID |
| `num_payment` | string | No | Payment number/reference |
| `comment` | string | No | Payment comment |
## Documents
### `dolibarr_documents_list`
List documents attached to an object.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `modulepart` | string | Yes | Module name (e.g. `"facture"`, `"propal"`, `"commande"`, `"societe"`) |
| `id` | number | No | Object ID |
| `ref` | string | No | Object ref (alternative to ID) |
### `dolibarr_document_download`
Download/get content of a document.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `modulepart` | string | Yes | Module name |
| `original_file` | string | Yes | Relative file path (e.g. `"FA2301-0001/FA2301-0001.pdf"`) |
### `dolibarr_document_builddoc`
Generate/build a document (e.g. PDF invoice).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `modulepart` | string | Yes | Module name |
| `original_file` | string | Yes | Expected output filename |
| `doctemplate` | string | No | Document template name (e.g. `"crabe"`, `"sponge"`) |
| `langcode` | string | No | Language code (e.g. `"en_US"`, `"fr_FR"`) |
## Members
### `dolibarr_members_list`
List association members.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `typeid` | number | No | Filter by member type ID |
| `status` | `"0"` / `"1"` / `"-1"` / `"-2"` | No | 1=validated, 0=draft, -1=resigned, -2=excluded |
| `search` | string | No | Search in name |
### `dolibarr_member_get`
Get a single member by ID.
## Stock / Warehouses
### `dolibarr_warehouses_list`
List warehouses. No additional parameters (supports pagination).
### `dolibarr_stockmovements_list`
List stock movements.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `product_id` | number | No | Filter by product ID |
| `warehouse_id` | number | No | Filter by warehouse ID |
### `dolibarr_stockmovement_create`
Create a stock movement (add/remove stock).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `product_id` | number | Yes | Product ID |
| `warehouse_id` | number | Yes | Warehouse ID |
| `qty` | number | Yes | Quantity (positive=add, negative=remove) |
| `type` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=increase, 1=decrease, 2=transfer increase, 3=transfer decrease |
| `label` | string | No | Movement label/reason |
| `inventorycode` | string | No | Inventory code |
## Bank Accounts
### `dolibarr_bankaccounts_list`
List bank accounts. No additional parameters (supports pagination).
### `dolibarr_bankaccount_lines`
List transactions/lines for a bank account.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Bank account ID |
## Categories
### `dolibarr_categories_list`
List categories.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | `"product"` / `"supplier"` / `"customer"` / `"member"` / `"contact"` / `"project"` | No | Category type |
| `search` | string | No | Search in label |
### `dolibarr_category_get`
Get a single category by ID.
### `dolibarr_category_create`
Create a new category.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `label` | string | Yes | Category label |
| `type` | string | Yes | Category type |
| `fk_parent` | number | No | Parent category ID (0 = root) |
| `description` | string | No | Category description |
| `color` | string | No | Category color (hex, e.g. `"ff0000"`) |
## Users
### `dolibarr_users_list`
List Dolibarr users.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search in login name |
### `dolibarr_user_get`
Get a single user by ID.
### `dolibarr_user_create`
Create a new Dolibarr user.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `login` | string | Yes | Login/username |
| `lastname` | string | Yes | Last name |
| `firstname` | string | No | First name |
| `email` | string | No | Email address |
| `admin` | `"0"` / `"1"` | No | 0=user, 1=admin |
| `employee` | `"0"` / `"1"` | No | 1=is employee |
## Setup / System
### `dolibarr_setup_company`
Get company/entity information. No parameters.
### `dolibarr_setup_dictionary`
Get dictionary entries (lookup tables).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | Dictionary type: `countries`, `regions`, `states`, `currencies`, `civilities`, `payment_types`, `shipping_methods`, `availability`, `order_methods`, `event_types`, `expense_report_types`, `ticket_types`, `ticket_severities`, `ticket_categories`, `units`, `legal_form`, `staff_range`, `typent` |
### `dolibarr_setup_modules`
List enabled Dolibarr modules. No parameters.
### `dolibarr_status`
Get Dolibarr instance status and version. No parameters.
## Generic
### `dolibarr_api_request`
Make a raw API request to any Dolibarr REST endpoint.
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `method` | `"GET"` / `"POST"` / `"PUT"` / `"DELETE"` | Yes | HTTP method |
| `endpoint` | string | Yes | API path (e.g. `"/thirdparties"`) |
| `body` | object | No | Request body for POST/PUT |
| `params` | object | No | Query parameters |
### `dolibarr_list_connections`
List all configured connections. No parameters.
## Revision History
| Date | Version | Author | Notes |
| --- | --- | --- | --- |
| 2026-05-07 | 0.0.1 | jmiller | Initial API reference (44 tools) |
| 2026-05-07 | 0.1.0 | jmiller | Expanded to 89 tools — shipments, contracts, interventions, expense reports, tickets, agenda events, payments, documents, members, stock movements, contact CRUD, task CRUD with timespent, dictionaries, bank transactions |
docs/ARCHITECTURE.md
-118
View File
@@ -1,118 +0,0 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: dolibarr-api-mcp.Documentation
INGROUP: dolibarr-api-mcp
REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
PATH: /docs/ARCHITECTURE.md
VERSION: 01.00.00
BRIEF: Architecture overview and design decisions
-->
# Architecture
## Overview
dolibarr-api-mcp is a Model Context Protocol (MCP) server that bridges AI assistants (Claude Code, Cursor, etc.) with Dolibarr's built-in REST API.
```
AI Assistant <--> MCP (stdio) <--> DolibarrClient <--> Dolibarr REST API
/api/index.php
```
## Components
### `src/index.ts` — Server Entry Point
Registers all MCP tools with the `McpServer` from `@modelcontextprotocol/sdk`. Each tool maps to one or more Dolibarr API endpoints. Uses Zod schemas for input validation.
Includes shared helpers:
- `formatResponse()` — normalizes Dolibarr error responses and success payloads into MCP text content
- `paginationQuery()` — builds `limit`, `page`, `sortfield`, `sortorder` query params
- `buildSqlFilter()` — constructs Dolibarr's `sqlfilters` parameter from structured clauses (supports AND/OR joins, proper escaping)
- `searchFilter()` — shortcut for `LIKE '%term%'` filters on a single field
### `src/client.ts` — HTTP Client
The `DolibarrClient` class handles all HTTP communication with Dolibarr instances:
- Uses `node:https` / `node:http` for requests (not `fetch`) to support self-signed TLS certificates on Node.js 24+
- Authenticates via `DOLAPIKEY` header (Dolibarr's native API key mechanism)
- Sends `Accept: application/json` and `Content-Type: application/json`
- Supports GET, POST, PUT, and DELETE methods
### `src/config.ts` — Configuration Loader
Loads connection details from `~/.dolibarr-api-mcp.json`. Supports multiple named connections with a configurable default. Respects the `DOLIBARR_API_MCP_CONFIG` environment variable for custom config paths.
### `src/types.ts` — Type Definitions
TypeScript interfaces for `DolibarrConnection`, `DolibarrConfig`, and `ApiResponse`.
### `scripts/setup.mjs` — Interactive Setup
Node.js script using `readline/promises` that walks users through creating the config file. Supports adding multiple connections incrementally.
## Design Decisions
### Why `node:https` instead of `fetch`?
Node.js 24's built-in `fetch` (undici-based) does not honor `NODE_TLS_REJECT_UNAUTHORIZED=0` for self-signed certificate bypass. The classic `node:https` module with `rejectUnauthorized: false` works reliably across all Node.js versions.
### Why `DOLAPIKEY` instead of Bearer tokens?
Dolibarr's REST API authenticates via the `DOLAPIKEY` HTTP header, not OAuth or Bearer tokens. This is Dolibarr's native mechanism — each user has a per-user API key that inherits that user's permissions. There is no token expiration; keys persist until manually regenerated.
### Why `PUT` instead of `PATCH`?
Dolibarr's API uses `PUT` for updates (full or partial), not `PATCH`. The API accepts partial payloads via PUT — only the fields you send are updated.
### Why `sqlfilters` with a builder?
Dolibarr's API supports a custom `sqlfilters` query parameter that allows server-side filtering with SQL-like expressions (e.g. `(t.nom:like:'%acme%')`). The `buildSqlFilter()` helper:
- Handles single-quote escaping to prevent injection
- Supports combining multiple clauses with AND/OR
- Provides `searchFilter()` as a concise shortcut for the common `LIKE` pattern
### Why per-connection API keys?
Each Dolibarr instance requires its own API key scoped to a specific user. Multi-instance support is a core use case — managing staging, production, and dev ERP environments from a single MCP server.
## Data Flow
1. AI assistant sends a tool call via MCP stdio transport
2. `index.ts` validates parameters with Zod and resolves the connection
3. `DolibarrClient` constructs the API URL, attaches the `DOLAPIKEY` header, and makes the HTTP request
4. Response is parsed as JSON and returned as MCP tool output
## API Module Coverage
| Dolibarr Module | Tools | Endpoints |
|----------------|-------|-----------|
| Third Parties | 5 | `/thirdparties` |
| Invoices | 6 | `/invoices`, `/invoices/{id}/lines`, `/invoices/{id}/validate`, `/invoices/{id}/settopaid` |
| Proposals | 7 | `/proposals`, `/proposals/{id}/lines`, `/proposals/{id}/validate`, `/proposals/{id}/close` |
| Orders | 4 | `/orders`, `/orders/{id}/validate` |
| Products | 5 | `/products`, `/products/{id}/stock` |
| Contacts | 2 | `/contacts` |
| Projects | 3 | `/projects` |
| Tasks | 2 | `/tasks` |
| Users | 2 | `/users` |
| Categories | 1 | `/categories` |
| Bank Accounts | 1 | `/bankaccounts` |
| Supplier Invoices | 1 | `/supplierinvoices` |
| Supplier Orders | 1 | `/supplierorders` |
| Warehouses | 1 | `/warehouses` |
| Setup | 2 | `/setup/company`, `/status` |
| Generic | 2 | Any endpoint, connection listing |
## Revision History
| Date | Version | Author | Notes |
| --- | --- | --- | --- |
| 2026-05-07 | 0.0.1 | jmiller | Initial architecture document |
docs/INSTALLATION.md
-172
View File
@@ -1,172 +0,0 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: dolibarr-api-mcp.Documentation
INGROUP: dolibarr-api-mcp
REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
PATH: /docs/INSTALLATION.md
VERSION: 01.00.00
BRIEF: Installation and setup instructions
-->
# Installation
## Prerequisites
- **Node.js** 20.0.0 or later
- **npm** (included with Node.js)
- A Dolibarr ERP/CRM instance (v14+) with the REST API module enabled
- A Dolibarr API key (generated per-user or via Setup > Security)
## Install
```sh
git clone https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp.git
cd dolibarr-api-mcp
npm install
npm run build
npm run setup
```
The setup wizard will prompt for:
1. **Connection name** — a label for this instance (e.g. `production`, `staging`)
2. **Dolibarr URL** — the base URL of the instance (e.g. `https://erp.example.com`)
3. **API key** — the Dolibarr API key for authentication
4. **TLS verification** — whether to skip certificate verification (for self-signed certs)
Run `npm run setup` again to add more connections.
## Enabling the Dolibarr REST API
1. Log in to Dolibarr as an admin
2. Go to **Home > Setup > Modules/Applications**
3. Find **API/Web services (REST server)** in the list
4. Click the toggle to enable it
5. The API will be available at `https://your-dolibarr.com/api/index.php`
## Generating an API Key
### Per-User API Key (Recommended)
1. Go to **Home > Users & Groups > Users**
2. Select the user that will be used for API access
3. On the user card, look for the **API key** field
4. Click **Generate** to create a key, or set one manually
5. Click **Save**
The user's permissions determine what the API key can access. Use a dedicated API user with appropriate permissions for production.
### System-Level API Key
1. Go to **Home > Setup > Security > Tokens & API**
2. Generate or configure the system API key
3. This key has broader access — use with caution
## Register with Claude Code
Add to your global Claude Code config (`~/.claude.json`):
```json
{
"mcpServers": {
"dolibarr-api": {
"type": "stdio",
"command": "node",
"args": ["/path/to/dolibarr-api-mcp/dist/index.js"]
}
}
}
```
Or add to a project-level `.mcp.json`:
```json
{
"mcpServers": {
"dolibarr-api": {
"command": "node",
"args": ["/path/to/dolibarr-api-mcp/dist/index.js"]
}
}
}
```
Restart Claude Code after adding the server.
## Configuration File
The config is stored at `~/.dolibarr-api-mcp.json`:
```json
{
"defaultConnection": "production",
"connections": {
"production": {
"baseUrl": "https://erp.example.com",
"apiKey": "your-api-key"
},
"staging": {
"baseUrl": "https://erp-staging.example.com",
"apiKey": "your-staging-key",
"insecure": true
}
}
}
```
| Field | Required | Description |
|-------|----------|-------------|
| `defaultConnection` | Yes | Name of the default connection |
| `connections` | Yes | Map of named connections |
| `baseUrl` | Yes | Dolibarr instance URL (no trailing slash) |
| `apiKey` | Yes | Dolibarr API key (`DOLAPIKEY` header auth) |
| `insecure` | No | Set `true` to skip TLS verification |
You can also set the `DOLIBARR_API_MCP_CONFIG` environment variable to use a config file at a custom path.
## Verification
After setup, verify the server starts correctly:
```sh
npm start
```
If configured correctly, the server will start listening on stdio. If the config is missing or invalid, it will print an error with instructions.
You can also test the connection by asking Claude to run `dolibarr_status` — this calls the `/api/index.php/status` endpoint and returns the Dolibarr version.
## Troubleshooting
### "Failed to load config" error
The config file `~/.dolibarr-api-mcp.json` is missing or malformed. Run `npm run setup` to create it.
### "terminated" or connection errors
- Verify the Dolibarr instance is reachable from your machine
- For self-signed certs, set `"insecure": true` in the connection config
- Ensure the API key is valid
### "Access denied" or 403 errors
- The API module may not be enabled in Dolibarr (see "Enabling the Dolibarr REST API" above)
- The API key user may lack permissions for the requested operation
- Check that the user has the correct roles in Dolibarr's permissions system
### "Error 404" on certain endpoints
- Some API endpoints require specific Dolibarr modules to be enabled (e.g. Projects module for `/projects`)
- Check **Setup > Modules** to ensure the relevant module is active
## Revision History
| Date | Version | Author | Notes |
| --- | --- | --- | --- |
| 2026-05-07 | 0.0.1 | jmiller | Initial installation guide |
docs/index.md
-17
View File
@@ -1,17 +0,0 @@
<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later -->
# dolibarr-api-mcp Documentation
## Documents
- [INSTALLATION.md](./INSTALLATION.md) — Prerequisites, install, setup wizard, Dolibarr API key generation, troubleshooting
- [ARCHITECTURE.md](./ARCHITECTURE.md) — Component overview, design decisions, data flow, API module coverage
- [API.md](./API.md) — Full MCP tool reference with parameter tables for all 45 tools
## Root Documents
- [README.md](../README.md) — Project overview, quick start, tool summary
- [CHANGELOG.md](../CHANGELOG.md) — Version history
- [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute, development workflow, commit conventions
- [SECURITY.md](../SECURITY.md) — Vulnerability reporting policy
src/config.ts
+1 -1
View File
@@ -18,7 +18,7 @@ import { resolve } from 'node:path';
import { homedir } from 'node:os';
import type { DolibarrConfig, DolibarrConnection } from './types.js';
const CONFIG_FILENAME = '.dolibarr-api-mcp.json';
const CONFIG_FILENAME = '.mcp_mokocrm.json';
export async function loadConfig(): Promise<DolibarrConfig> {
const config_path = process.env.DOLIBARR_API_MCP_CONFIG