goldautumn2000/mcp-glpi repository overview

⁠mcp-glpi

把 GLPI(IT 服务管理平台)以 MCP 协议暴露成 HTTP 服务,让企业微信智能机器人、Claude、Cursor 等 AI 助手能够直接查询和处理工单、资产、用户等数据。

传输方式采用 Streamable HTTP。服务无状态,每个请求独立处理,一个进程即可支撑多个使用者同时调用。查询结果带有体积上限与自动裁剪,避免过大的 JSON 撑爆客户端长度限制导致对话失败。

基于 node:20-alpine,默认暴露 3000 端口。

⁠功能

共 86 个工具,按对象分类。

⁠工单 23 个

查询类包含工单列表、按条件搜索(状态、处理人、请求人、分类、实体、优先级、时间段、标题关键词、只看未完结)、工单详情、时间线(跟进与任务与解决方案与审批按时间合并)、跟进/任务/解决方案/审批/附件子列表、满意度调查结果、超期未完结工单。

写入类包含新建、修改、删除、追加跟进、添加任务(可记工时)、添加解决方案、指派给用户或组、工单关联、发起审批、处理审批、上传文件为文档、把已有文档挂到工单。

⁠问题单与变更单 8 个

两种对象的列表、详情、新建、修改,返回时附带状态中文标签。

⁠资产 17 个

计算机、软件、网络设备、打印机、显示器、电话的列表与详情;计算机的新增、修改、删除;按使用人查设备,同时用中文姓名与域账号两路匹配 contact 字段并合并结果,域账号重名时自动尝试数字序号。

⁠用户与用户组 8 个

用户列表、按登录名或姓名搜索、详情、新建;用户组的列表、详情、新建、把用户加入组。

⁠基础数据 5 个

工单分类、实体、文档。

⁠知识库 4 个

文章列表、详情、按标题搜索、新建。

⁠合同、供应商、位置、项目 13 个

各自的列表、详情,以及可写对象的创建与修改。

⁠统计 3 个

工单按状态统计、各类资产总量统计、按维度(状态/分类/技术员/实体/月)统计并支持时间区间。

⁠通用检索与会话 5 个

多条件搜索(字段名动态解析,支持 AND/OR/AND NOT/OR NOT)、记录总数探测、可搜索字段目录、当前 API 账号的权限概况,以及一个保留的兼容接口。

⁠工程特性

• 动态字段映射:通过 /listSearchOptions 解析字段名与 id 的对应关系,适配不同 GLPI 版本

• 会话自动续期:GLPI 会话过期返回 401 时自动重新登录,5xx 与 429 自动重试

• 外键自动解析:返回 technician、category、entity 等 id 的同时给出名称

• 结果体积控制:列表默认 20 条、单次请求上限 200 条,超过体积上限时自动裁剪并提示缩小查询范围

• 运行日志:包含时间、调用方 IP、工具名、参数、结果摘要与耗时

⁠快速开始

docker run -d --name mcp-glpi \
  -p 3000:3000 \
  -e GLPI_URL="https://glpi.example.com" \
  -e GLPI_APP_TOKEN="你的应用令牌" \
  -e GLPI_USER_TOKEN="你的用户令牌" \
  -e MCP_SERVICE_TOKEN="换成一串随机字符串" \
  <你的镜像地址>

例:<你的镜像地址> 形如 your-dockerhub-user/mcp-glpi:latest,替换成实际发布的镜像名。

启动后确认服务可用:

curl http://127.0.0.1:3000/health
# {"status":"ok","service":"mcp-glpi"}

⁠环境变量

⁠GLPI 连接

鉴权二选一:GLPI_USER_TOKEN,或 GLPI_USERNAME + GLPI_PASSWORD。

⁠MCP HTTP 服务

⁠返回结果体积控制

客户端对单次返回长度有上限,企业微信尤为明显,返回过大会直接触发「暂时无法回答,请稍后再试」。默认值按常见平台留了余量,可按实际平台调小。

⁠HTTP 接口

鉴权令牌支持三种传递方式,任选其一:

• Authorization: Bearer <MCP_SERVICE_TOKEN>

• X-API-Key: <MCP_SERVICE_TOKEN>

• 查询参数 ?apiKey=<MCP_SERVICE_TOKEN>

上传文件为文档时,glpi_upload_document 读取的是容器内路径,需要把宿主机目录挂载进容器,例如 -v /host/uploads:/uploads,再把 file_path 传 /uploads/xxx.pdf。

⁠接入企业微信智能机器人

在企业微信管理后台创建机器人后,为机器人添加 MCP 插件,按下表填写。

如果控制台里用的是 Query 方式,则 Parameter name 填 apiKey,值填令牌本身(不带 Bearer 前缀),同样可用。

前置条件:该地址需能从公网以 HTTPS 访问,通常用 Nginx 反向代理到容器的 3000 端口。反向代理要转发 Authorization 头,并设置 X-Forwarded-For,服务日志里的调用方 IP 依赖它:

location /mcp {
    proxy_pass http://127.0.0.1:3000/mcp;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Authorization $http_authorization;
    proxy_buffering off;
    proxy_read_timeout 3600s;
}

⁠接入其它 MCP 客户端

以支持远程 HTTP 的客户端为例,把 URL 指向 /mcp 并带上令牌:

{
  "mcpServers": {
    "glpi": {
      "type": "http",
      "url": "https://你的域名/mcp",
      "headers": {
        "Authorization": "Bearer 你的 MCP_SERVICE_TOKEN"
      }
    }
  }
}

⁠安全建议

/mcp 背后的工具包含删除工单、删除资产等不可恢复的操作。部署时建议同时做到:

• 始终设置 MCP_SERVICE_TOKEN,不要以无鉴权状态暴露到公网

• 为 GLPI 侧的 API 账号只授予业务所需的权限与实体范围

• 反向代理上开启 HTTPS,并限制来源 IP 或叠加访问控制

⁠赞赏支持

如果这个项目对你有帮助,欢迎扫码支持一下。

⁠许可证

MIT

本项目基于 GMS64260/mcp-glpi⁠ 扩展,增加了 Streamable HTTP 传输、查询结果体积控制,以及面向企业微信智能机器人的接入适配。

本仓库地址:goldautumn2000/mcp-glpi⁠