mcp-mokocrm-api/README.md

# dolibarr-api-mcp

MCP server for Dolibarr ERP/CRM REST API operations

![Language](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white) ![License](https://img.shields.io/badge/license-GPL--3.0--or--later-green?style=flat-square) ![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen?style=flat-square&logo=node.js&logoColor=white) ![MCP](https://img.shields.io/badge/MCP-1.12+-blue?style=flat-square) ![Wiki](https://img.shields.io/badge/wiki-dolibarr--api--mcp-blue?style=flat-square)

| Field | Value |
|---|---|
| **Language** | TypeScript |
| **License** | GPL-3.0-or-later |
| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp) |
| **Node.js** | >= 20.0.0 |
| **MCP SDK** | @modelcontextprotocol/sdk ^1.12.1 |

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that bridges AI assistants (Claude Code, Cursor, etc.) with Dolibarr's built-in REST API. Manage invoices, proposals, orders, products, third parties, projects, and more -- directly from your AI assistant.

---

## Quick Start

```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 interactive setup wizard will prompt for your Dolibarr instance URL, API key, and TLS settings.

Register with Claude Code (`~/.claude.json`):

```json
{
  "mcpServers": {
    "dolibarr-api": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/dolibarr-api-mcp/dist/index.js"]
    }
  }
}
```

Verify with: `dolibarr_status` -- returns the Dolibarr version and server info.

---

## Tools (85)

Every tool accepts an optional `connection` parameter to target a specific named Dolibarr instance (defaults to the configured default).

### Third Parties (5)

| Tool | Description |
|---|---|
| `dolibarr_thirdparties_list` | List/search third parties with pagination and SQL filters |
| `dolibarr_thirdparty_get` | Get a third party by ID |
| `dolibarr_thirdparty_create` | Create a new third party (customer, supplier, or prospect) |
| `dolibarr_thirdparty_update` | Update an existing third party |
| `dolibarr_thirdparty_delete` | Delete a third party |

### Contacts (5)

| Tool | Description |
|---|---|
| `dolibarr_contacts_list` | List/search contacts with pagination |
| `dolibarr_contact_get` | Get a contact by ID |
| `dolibarr_contact_create` | Create a new contact linked to a third party |
| `dolibarr_contact_update` | Update an existing contact |
| `dolibarr_contact_delete` | Delete a contact |

### Invoices (7)

| Tool | Description |
|---|---|
| `dolibarr_invoices_list` | List/search invoices with status and date filters |
| `dolibarr_invoice_get` | Get an invoice by ID |
| `dolibarr_invoice_create` | Create a new invoice for a third party |
| `dolibarr_invoice_add_line` | Add a line item to an invoice |
| `dolibarr_invoice_validate` | Validate a draft invoice |
| `dolibarr_invoice_set_paid` | Mark an invoice as paid |
| `dolibarr_invoice_add_payment` | Record a payment against an invoice |
| `dolibarr_invoice_payments` | List payments for an invoice |

### Proposals / Quotes (7)

| Tool | Description |
|---|---|
| `dolibarr_proposals_list` | List/search proposals with pagination |
| `dolibarr_proposal_get` | Get a proposal by ID |
| `dolibarr_proposal_create` | Create a new proposal for a third party |
| `dolibarr_proposal_add_line` | Add a line item to a proposal |
| `dolibarr_proposal_validate` | Validate a draft proposal |
| `dolibarr_proposal_close` | Close a proposal (signed or refused) |

### Orders (5)

| Tool | Description |
|---|---|
| `dolibarr_orders_list` | List/search orders with pagination |
| `dolibarr_order_get` | Get an order by ID |
| `dolibarr_order_create` | Create a new order for a third party |
| `dolibarr_order_add_line` | Add a line item to an order |
| `dolibarr_order_validate` | Validate a draft order |

### Products & Services (5)

| Tool | Description |
|---|---|
| `dolibarr_products_list` | List/search products and services |
| `dolibarr_product_get` | Get a product by ID |
| `dolibarr_product_create` | Create a new product or service |
| `dolibarr_product_update` | Update an existing product |
| `dolibarr_product_stock` | Get stock levels for a product |

### Projects (4)

| Tool | Description |
|---|---|
| `dolibarr_projects_list` | List/search projects |
| `dolibarr_project_get` | Get a project by ID |
| `dolibarr_project_create` | Create a new project |
| `dolibarr_project_update` | Update an existing project |

### Tasks (6)

| Tool | Description |
|---|---|
| `dolibarr_tasks_list` | List tasks (optionally filtered by project) |
| `dolibarr_task_get` | Get a task by ID |
| `dolibarr_task_create` | Create a new task within a project |
| `dolibarr_task_update` | Update an existing task |
| `dolibarr_task_timespent_list` | List time entries for a task |
| `dolibarr_task_timespent_add` | Add a time entry to a task |

### Contracts (4)

| Tool | Description |
|---|---|
| `dolibarr_contracts_list` | List/search contracts |
| `dolibarr_contract_get` | Get a contract by ID |
| `dolibarr_contract_create` | Create a new contract |
| `dolibarr_contract_validate` | Validate a draft contract |

### Shipments (5)

| Tool | Description |
|---|---|
| `dolibarr_shipments_list` | List/search shipments |
| `dolibarr_shipment_get` | Get a shipment by ID |
| `dolibarr_shipment_create` | Create a new shipment from an order |
| `dolibarr_shipment_validate` | Validate a draft shipment |
| `dolibarr_shipment_close` | Close a shipment |

### Agenda Events (4)

| Tool | Description |
|---|---|
| `dolibarr_agendaevents_list` | List/search agenda events |
| `dolibarr_agendaevent_get` | Get an agenda event by ID |
| `dolibarr_agendaevent_create` | Create a new agenda event |
| `dolibarr_agendaevent_update` | Update an existing agenda event |

### Tickets (3)

| Tool | Description |
|---|---|
| `dolibarr_tickets_list` | List/search tickets |
| `dolibarr_ticket_get` | Get a ticket by ID |
| `dolibarr_ticket_create` | Create a new support ticket |

### Members (2)

| Tool | Description |
|---|---|
| `dolibarr_members_list` | List/search members (foundation/association module) |
| `dolibarr_member_get` | Get a member by ID |

### Users (3)

| Tool | Description |
|---|---|
| `dolibarr_users_list` | List Dolibarr users |
| `dolibarr_user_get` | Get a user by ID |
| `dolibarr_user_create` | Create a new Dolibarr user |

### Expense Reports (3)

| Tool | Description |
|---|---|
| `dolibarr_expensereports_list` | List/search expense reports |
| `dolibarr_expensereport_get` | Get an expense report by ID |
| `dolibarr_expensereport_create` | Create a new expense report |

### Interventions (2)

| Tool | Description |
|---|---|
| `dolibarr_interventions_list` | List/search interventions |
| `dolibarr_intervention_get` | Get an intervention by ID |

### Documents (3)

| Tool | Description |
|---|---|
| `dolibarr_documents_list` | List documents attached to a module element |
| `dolibarr_document_download` | Download a document file |
| `dolibarr_document_builddoc` | Generate a PDF document for an element |

### Stock & Warehouses (3)

| Tool | Description |
|---|---|
| `dolibarr_warehouses_list` | List warehouses |
| `dolibarr_stockmovements_list` | List stock movements |
| `dolibarr_stockmovement_create` | Create a stock movement |

### Bank Accounts (2)

| Tool | Description |
|---|---|
| `dolibarr_bankaccounts_list` | List bank accounts |
| `dolibarr_bankaccount_lines` | List transaction lines for a bank account |

### Categories (3)

| Tool | Description |
|---|---|
| `dolibarr_categories_list` | List categories by type |
| `dolibarr_category_get` | Get a category by ID |
| `dolibarr_category_create` | Create a new category |

### Supplier Invoices & Orders (2)

| Tool | Description |
|---|---|
| `dolibarr_supplier_invoices_list` | List supplier (vendor) invoices |
| `dolibarr_supplier_orders_list` | List supplier (vendor) orders |

### Setup & System (5)

| Tool | Description |
|---|---|
| `dolibarr_status` | Check Dolibarr instance status and version |
| `dolibarr_setup_company` | Get company/organization setup info |
| `dolibarr_setup_modules` | List enabled Dolibarr modules |
| `dolibarr_setup_dictionary` | Query Dolibarr dictionary tables (countries, currencies, etc.) |
| `dolibarr_list_connections` | List all configured Dolibarr connections |

### Generic (1)

| Tool | Description |
|---|---|
| `dolibarr_api_request` | Make a raw API request to any Dolibarr endpoint |

---

## Configuration

The config file is stored at `~/.dolibarr-api-mcp.json` (or set `DOLIBARR_API_MCP_CONFIG` for a custom path):

```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 (self-signed certs) |

---

## Architecture

```
AI Assistant  <-->  MCP (stdio)  <-->  DolibarrClient  <-->  Dolibarr REST API
                                                              /api/index.php
```

- **Transport**: stdio (standard input/output)
- **Auth**: `DOLAPIKEY` HTTP header (Dolibarr's native per-user API key)
- **HTTP**: Uses `node:https`/`node:http` (not `fetch`) for reliable self-signed TLS support on Node.js 24+
- **Validation**: Zod schemas for all tool inputs
- **Filtering**: `buildSqlFilter()` helper for Dolibarr's `sqlfilters` parameter with injection-safe escaping

### Source Layout

| File | Purpose |
|---|---|
| `src/index.ts` | Server entry point -- registers all MCP tools with Zod schemas |
| `src/client.ts` | `DolibarrClient` HTTP class (GET/POST/PUT/DELETE) |
| `src/config.ts` | Configuration loader for multi-instance connections |
| `src/types.ts` | TypeScript interfaces (`DolibarrConnection`, `DolibarrConfig`, `ApiResponse`) |
| `scripts/setup.mjs` | Interactive setup wizard for creating the config file |
| `config.example.json` | Example configuration with multiple connections |

---

## Examples

**List all customers:**
```
dolibarr_thirdparties_list with search="acme", limit=10
```

**Create an invoice and add a line:**
```
dolibarr_invoice_create with socid=42
dolibarr_invoice_add_line with id=<invoice_id>, desc="Consulting services", subprice=150.00, qty=8
dolibarr_invoice_validate with id=<invoice_id>
```

**Check a specific Dolibarr instance:**
```
dolibarr_status with connection="staging"
```

**Raw API request for unsupported endpoints:**
```
dolibarr_api_request with method="GET", endpoint="/categories", params={"type": "product"}
```

---

## Guides

| Page | Description |
|---|---|
| [INSTALLATION](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/wiki/INSTALLATION) | Prerequisites, install steps, Claude Code registration, troubleshooting |

## Reference

| Page | Description |
|---|---|
| [ARCHITECTURE](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/wiki/ARCHITECTURE) | Component overview, design decisions, data flow, API module coverage |

---

## Documentation

Full documentation is available on the [Wiki](https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp/wiki).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and contribution instructions.

## License

This project is licensed under the GNU General Public License v3.0 or later -- see the [LICENSE](LICENSE) file.

---

*[Moko Consulting](https://mokoconsulting.tech) -- [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*