Dolibarr MCP 服务器端实现

关键词

DolibarrERP 集成模型上下文协议JSON-RPCHTTP 流式传输

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个基于 Model Context Protocol（MCP）的服务器端，用于将 Dolibarr ERP/CRM 的功能以统一的 MCP 服务暴露给各类 MCP 客户端（如 Claude Desktop、LM Studio 等）。
    • 服务端包含对 Dolibarr 各模块的 CRUD 能力、搜索能力、以及原始 API 调用入口，支持通过工具（Tools）注册并供 LLM 调用。

  • 主要功能点

    • MCP 服务端核心能力
      • 提供工具集（Tools），用于执行 Dolibarr 的各类操作（如用户、客户、产品、发票、订单、项目、联系人等的创建、读取、更新、删除等）。
      • 提供简化的搜索工具（如按引用、按名称/标签等进行服务端过滤，避免将大量数据拉回上下文）。
      • 支持原始 API 调用入口，供需要更低层次操作的场景使用。
      • 会话管理、能力声明、以及对传输协议的支持（STDIO 与 HTTP 流式传输）。
    • 支持的传输和接口
      • STDIO：默认作为 Claude Desktop 等 MCP 客户端的本地交互通道。
      • HTTP（Streamable HTTP）：开启 MCP_TRANSPORT=http，可通过 Open WebUI、LM Studio 等远程客户端访问。
    • 兼容性与容错
      • 通过统一的 DolibarrClient 实现对 Dolibarr REST API 的包装、错误处理、以及输入校验（包括自动生成引用、字段别名、字段校验等）。
      • 提供专门的测试与集成用例，覆盖多种数据结构和场景。

  • 安装步骤

    • 克隆仓库并进入目录
    • 创建并激活虚拟环境
    • 安装开发版本（易于本地开发与测试）
    • 运行服务器：有两种模式可选
      • STDIO 模式（默认）：在前台运行 Python 模块 dolibarr_mcp_server，维持与 MCP 客户端的 STDIO 通道
      • HTTP 模式：设置 MCP_TRANSPORT=http 后执行运行，服务器将以流式 HTTP 提供 MCP 服务
    • 测试连接：提供 test_connection、test API 等工具，用于在接入前验证 Dolibarr 的可用性

  • 服务器配置（MCP 客户端配置示例描述） 说明：MCP 客户端需要提供一个 JSON 配置，用于启动并连接到 MCP 服务器。配置包含服务器的名称、启动命令、参数以及工作路径等信息。以下为配置项要点（请以文本方式理解，不要直接粘贴代码块）：

    • server: dolibarr
    • command: 指向 Python 解释器的完整路径（例如在虚拟环境中的 python 可执行文件所在路径）
    • args: 数组，包含模块执行方式，例如 -m dolibarr_mcp.dolibarr_mcp_server
    • cwd: MCP 服务器所在根目录的路径
    • env: 环境变量集合，包括 DOLIBARR_URL、DOLIBARR_API_KEY 等 Dolibarr 相关凭证和配置
    • 说明：客户端不需要了解服务器内部实现细节，只需要知道如何启动服务器以及如何提供 Dolibarr 的连接信息。服务器端会通过 MCP 协议对外暴露工具与资源。

  • 基本使用方法

    • 启动方式
      • STDIO：在服务器端虚拟环境中执行 python -m dolibarr_mcp.dolibarr_mcp_server，默认作为 MCP 客户端的 STDIO 通道。
      • HTTP：将 MCP_TRANSPORT 设置为 http 并设置主机与端口（如 MCP_HTTP_HOST、MCP_HTTP_PORT），再以相同方式启动服务器，客户端通过 http://主机:端口/ 进行连接。
    • 客户端接入
      • 在 Claude Desktop、LM Studio 等 MCP 客户端中添加新的 MCP 服务器，使用上述服务器启动命令配置（CLI 客户端无需修改），并提供 Dolibarr API 的访问点（DOLIBARR_URL、DOLIBARR_API_KEY 等环境变量）。
    • 测试与排错
      • 使用仓库中提供的 test_connection/测试工具，先在本地验证 Dolibarr 的连通性与 API 状态，再将服务器投入正式使用。
      • 通过 HTTP 模式可在本地进行远程连接测试，确保 MCP 协议头头部信息（如 mcp-protocol-version）被正确处理。

  • 备注

    • 该实现尽量覆盖 Dolibarr 的主要对象（用户、客户、产品、发票、订单、联系人、项目、对原始 API 的调用等），并提供多种工具，便于 LLM 客户端以最小的上下文占用完成所需操作。
    • 若要深入自定义，请查阅仓库中的文档与示例配置，结合 Dolibarr API 的实际部署环境进行配置。

服务器信息

访问项目