内容
# Dolibarr MCP 服务器
Dolibarr MCP（模型上下文协议）服务器，允许LLM或AI代理通过其REST API与Dolibarr实例交互。
## 特性
- **动态发现**：通过Swagger/OpenAPI自动探索模块和端点
- **19种MCP工具**：CRUD，文档管理，商业工作流，项目/时间，联系人，额外字段
- **兼容Dolibarr v18-22+**：适应您的版本
- **自定义模块**：与第三方模块一起工作
- **双重传输**：stdio（CLI）或HTTP（Web）
## 架构
```
LLM ←→ MCP Server (PHP) ←→ Dolibarr REST API
↓
Swagger Schema (动态发现)
```
## 要求
- PHP 8.1+
- Composer
- 启用REST API的Dolibarr实例
- Dolibarr API密钥（DOLAPIKEY）
## 安装
```bash
git clone https://github.com/momodemo333/dolibarr-mcp-server.git
cd dolibarr-mcp-server
php8.1 $(which composer) install
cp .env.example .env
# 编辑.env文件，填写您的值
```
## 配置
### 环境变量
在根目录创建`.env`文件：
```env
DOLIBARR_URL=https://您的Dolibarr实例.com
DOLIBARR_API_KEY=您的API密钥
```
### Claude Desktop 配置
在MCP配置中添加：
**Linux**：`~/.config/claude/claude_desktop_config.json`
**macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"dolibarr": {
"command": "php8.1",
"args": ["/路径/到/dolibarr-mcp-server/bin/server.php"],
"env": {
"DOLIBARR_URL": "https://您的Dolibarr实例.com",
"DOLIBARR_API_KEY": "您的API密钥"
}
}
}
}
```
### MCP JSON 配置
为兼容MCP的客户端提供`.mcp.json.example`文件作为模板。复制到本地并调整路径/变量，但不要提交您的凭证。
## 可用工具
### 通用CRUD（6种工具）
| 工具 | 描述 |
|-------|-------------|
| `dolibarr_api_explorer` | 发现模块、端点和参数 |
| `dolibarr_list` | 列出资源，支持筛选和分页 |
| `dolibarr_get` | 按ID检索资源 |
| `dolibarr_create` | 创建资源 |
| `dolibarr_update` | 更新资源 |
| `dolibarr_delete` | 删除资源 |
### 商业工作流（3种工具）
| 工具 | 描述 |
|-------|-------------|
| `dolibarr_action` | 执行操作（验证、关闭、重新打开...） |
| `dolibarr_add_line` | 向报价单、订单、发票添加行 |
| `dolibarr_create_from` | 从另一个文档创建文档（报价单 → 订单 → 发票） |
### 联系人管理（2种工具）
| 工具 | 描述 |
|-------|-------------|
| `dolibarr_link_contact` | 将联系人链接或解除链接到文档（BILLING、SHIPPING、CUSTOMER） |
| `dolibarr_get_contacts` | 列出与文档相关的联系人 |
### 项目/时间（1种工具）
| 工具 | 描述 |
|-------|-------------|
| `dolibarr_add_time_spent` | 通过`/tasks/{id}/addtimespent`向项目任务添加时间记录，失败时提供清晰的诊断信息 |
### 文档管理（5种工具）
| 工具 | 描述 |
|-------|-------------|
| `dolibarr_documents_list` | 列出附件文档 |
| `dolibarr_documents_upload` | 上传文档 |
| `dolibarr_documents_download` | 下载文档 |
| `dolibarr_documents_builddoc` | 生成PDF |
| `dolibarr_documents_delete` | 删除文档 |
### 额外字段（2种工具）
| 工具 | 描述 |
|-------|-------------|
| `dolibarr_extrafield_update` | 修改自定义字段 |
| `dolibarr_extrafield_delete` | 删除自定义字段 |
## 支持的模块
`thirdparties`, `contacts`, `products`, `invoices`, `supplierinvoices`, `orders`, `supplierorders`, `proposals`, `categories`, `users`, `projects`, `contracts`, 以及您实例中启用的所有模块。
## 使用示例
```
"探索Dolibarr中可用的模块"
"列出最近的10张发票"
"为客户X创建报价单，包含2行"
"验证订单123"
"生成发票F2501942的PDF"
"将联系人Dupont链接到订单作为计费联系人"
```
## 项目结构
```
dolibarr-mcp-server/
├── bin/
│ └── server.php # MCP入口点（stdio）
├── public/
│ └── index.php # HTTP入口点
├── src/
│ ├── Bootstrap.php # 环境加载 + 服务器构建
│ ├── Container.php # DI容器（PSR-11）
│ ├── Client/
│ │ ├── DolibarrClient.php # Dolibarr API的HTTP客户端
│ │ └── ApiSchemaClient.php # Swagger/OpenAPI解析器
│ ├── Support/
│ │ └── FieldMapper.php # 字段名称自动纠正
│ └── Tools/
│ ├── CrudTools.php # 通用CRUD（列表、获取、创建、更新、删除）
│ ├── ExplorerTools.php # API发现
│ ├── ActionTools.php # 工作流操作（验证、关闭...）
│ ├── LineTools.php # 行管理 + 从文档创建
│ ├── ContactTools.php # 联系人管理
│ ├── DocumentTools.php # 文档管理（PDF、上传、下载）
│ └── ExtrafieldTools.php # 自定义字段
├── tests/
│ ├── Support/
│ │ └── FieldMapperTest.php
│ └── Tools/
│ ├── CrudToolsTest.php
│ ├── ActionToolsTest.php
│ ├── LineToolsTest.php
│ ├── ContactToolsTest.php
│ ├── DocumentToolsTest.php
│ └── ExtrafieldToolsTest.php
├── .env.example # 环境变量模板
├── .mcp.json.example # MCP配置模板
├── composer.json
├── phpunit.xml
├── LLM.md # 详细的使用指南
├── CHANGELOG.md
└── README.md
```
## 测试
```bash
php8.1 vendor/bin/phpunit
```
## 附加文档
- [LLM.md](LLM.md) — 详细的使用指南，包含参数、示例和最佳实践
- [CHANGELOG.md](CHANGELOG.md) — 版本历史
## 兼容性
| 组件 | 版本 |
|-----------|---------|
| Dolibarr | v18.0+（测试到v22） |
| PHP | 8.1+ |
| MCP协议 | 2024-11-05 |
| SDK | php-mcp/server ^3.3 |
## 许可证
MIT
