mcp-mokocrm-api/docs/INSTALLATION.md

<!--
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 |