GLPI MCP

GLPI MCP 服务是一个基于 Python 的模型上下文协议（MCP）服务，适用于 GLPI IT 服务管理平台。它通过 GLPI 的高级 API（/api.php，OAuth2）进行通信，让 AI 助手和自动化工具能够访问工单、变更和问题（及其时间线和团队）、资产、用户、群组、实体、知识库和文档，还提供可访问 GLPI 所有端点的通用工具。它支持读取和写入操作，并提供只读和试运行模式、按用户进行 GLPI 访问，以及供远程 MCP 客户端使用的 OAuth 登录。

✨ 功能

核心功能

• 按状态、类型、优先级、类别、实体、日期、文本或任意 RSQL 筛选条件搜索工单、变更和问题
• 读取项目的完整时间线：后续跟进、任务、解决方案、审批和文档
• 搜索和读取各种类型的资产（包括自定义资产），并查看财务信息
• 查找用户、群组、实体和配置文件
• 搜索和读取知识库文章；下载文档
• 从 GLPI 自带的 OpenAPI 文档中发现所有端点和架构，无需针对特定 GLPI 版本硬编码

管理操作

• 创建、更新和删除工单、变更和问题（如果已启用）
• 添加后续跟进、任务、解决方案和审批请求
• 指派技术人员和群组，添加请求者和观察者
• 创建、更新和删除资产及知识库文章
• 使用通用工具在任意端点创建、更新和删除项目

高级功能

• 支持 GLPI 11.0.6 及更高版本（API 2.3）和 GLPI 12（API 3.0；也可固定使用 2.3）；自动检测版本并在每个请求中固定版本
• OAuth 密码授权，支持令牌缓存和续期
• 按用户进行访问：传递令牌，或使用 GLPI 账户登录（OAuth 登录），供远程 MCP 客户端使用
• 通过外部身份提供方进行 OIDC 登录，或使用静态 bearer 令牌
• 只读模式、试运行模式和基于标签的工具筛选
• 将 HTML 富文本转换为纯文本，以节省令牌
• 速率限制、响应大小限制，以及可选的工具搜索转换
• 多种传输选项（STDIO、SSE、HTTP）和可选的 Sentry 集成

🚀 安装

前提条件

• Python 3.11 至 3.15
• GLPI 11.0.6 或更高版本（包括 12.x）。不支持 GLPI 10 和 GLPI 11.0.0-11.0.5， 因为它们缺少高级 API 2.3
• 已在 Setup > General > API 中启用 API（“Enable API”）
• 一个 OAuth 客户端（参见 GLPI 设置）

从 PyPI 快速安装

最简单的入门方式是从 PyPI 安装：

# Using UV (recommended)
uvx glpi-mcp-server

# Or using pip
pip install glpi-mcp-server

运行服务前，请记得为 GLPI 实例配置环境变量：

# Create environment configuration
export GLPI_URL=https://glpi.example.com
export GLPI_CLIENT_ID=your-client-id
export GLPI_CLIENT_SECRET=your-client-secret
export GLPI_USERNAME=glpi-mcp
export GLPI_PASSWORD=change-me

从源代码安装

1. 克隆仓库：

git clone https://github.com/mhajder/glpi-mcp.git
cd glpi-mcp

2. 安装依赖项：

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 配置环境变量：

cp .env.example .env
# Edit .env with your GLPI URL and OAuth credentials

4. 运行服务：

# Using UV (recommended)
uv run glpi-mcp

# Or using the installed command directly
glpi-mcp

使用 Docker

GitHub Packages 提供了 Docker 镜像，便于部署。镜像会在端口 8000（/mcp）上运行 HTTP Streamable 传输。

docker pull ghcr.io/mhajder/glpi-mcp:latest

启用 GLPI 登录或 OIDC 后，请在 /data 上挂载 卷，以便在容器重建后保留 OAuth 客户端注册信息。

Open WebUI

Open WebUI 0.6.31 及更高版本可直接连接到该镜像。在 Open WebUI 中，前往 管理设置 > 集成 > 外部工具服务，添加一个类型为 MCP（Streamable HTTP） 的连接，URL 填写 http://<host>:8000/mcp，并将 Bearer 身份验证设置为你的 MCP_HTTP_BEARER_TOKEN。

启用 GLPI 登录或 OIDC 后，请改用 公开 URL + /mcp，并选择 OAuth 2.1 身份验证；Open WebUI 会将自身注册为客户端，因此如果 你限制了重定向 URI，请添加你的 Open WebUI URL。

开发环境设置

如需使用其他工具进行开发：

# Clone and install with development dependencies
git clone https://github.com/mhajder/glpi-mcp.git
cd glpi-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup prek hooks
uv run prek install

🔧 配置

GLPI 设置

1. 启用 API：设置 > 常规 > API >“启用 API”。
2. 创建 OAuth 客户端：设置 > OAuth 客户端 > 添加。
   • 授权类型：密码（用于 GLPI_USERNAME/GLPI_PASSWORD）。如需使用 GLPI 登录，请添加 授权码。
   • 作用域：api 和 user。如需使用 glpi_graphql_query，请添加 graphql。
   • 如需使用 GLPI 登录，请将重定向 URI 设置为 GLPI_OAUTH_BASE_URL + GLPI_OAUTH_REDIRECT_PATH。
   • 复制生成的客户端 ID 和密钥。
3. 为服务创建 GLPI 用户（例如 glpi-mcp），并为其设置仅包含工具所需权限的配置文件。 除非启用了按用户访问，否则每次工具调用都以该用户的身份执行。

环境变量

# GLPI Connection Details
# GLPI root URL, without /api.php
GLPI_URL=https://glpi.example.com

# OAuth client from Setup > OAuth clients
GLPI_CLIENT_ID=your-client-id
GLPI_CLIENT_SECRET=your-client-secret

# GLPI account the tools act as (OAuth password grant)
GLPI_USERNAME=glpi-mcp
GLPI_PASSWORD=change-me

# OAuth scopes, space- or comma-separated (default: api user)
GLPI_SCOPES=api user

# High-Level API version: auto (default), 2.3 or 3.0
GLPI_API_VERSION=auto

# Optional: entity and profile to work in
# GLPI_ENTITY=0
# GLPI_ENTITY_RECURSIVE=true
# GLPI_PROFILE=4

# SSL Configuration
GLPI_VERIFY_SSL=true
GLPI_TIMEOUT=30

# Per-user GLPI access (HTTP transports only; pick at most one)
# GLPI_TOKEN_PASSTHROUGH=false
# GLPI_OAUTH_LOGIN=false
# GLPI_OAUTH_BASE_URL=https://glpi-mcp.example.com
# GLPI_OAUTH_REDIRECT_PATH=/auth/callback
# GLPI_OAUTH_ALLOWED_REDIRECT_URIS=

# Read-Only Mode
READ_ONLY_MODE=false

# Dry-Run Mode
DRY_RUN_MODE=false

# Disabled Tags
# Example: DISABLED_TAGS=assets,knowledgebase,graphql
DISABLED_TAGS=

# Response Size Limit (bytes; empty = unlimited)
# RESPONSE_MAX_SIZE=500000

# Logging Configuration
LOG_LEVEL=INFO

# Rate Limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
TOOL_SEARCH_ENABLED=false
TOOL_SEARCH_STRATEGY=bm25
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# SENTRY_DSN=https://[email protected]/6789

# MCP Transport Configuration
# 'stdio' (default), 'sse' or 'http' ('streamable-http' is an alias for 'http')
MCP_TRANSPORT=stdio
# MCP_HTTP_HOST=127.0.0.1
# MCP_HTTP_PORT=8000
# MCP_HTTP_BEARER_TOKEN=

# OIDC / OAuth Authentication (optional, for remote hosting)
# OIDC_CONFIG_URL=https://id.example.com/.well-known/openid-configuration
# OIDC_CLIENT_ID=
# OIDC_CLIENT_SECRET=
# OIDC_BASE_URL=https://glpi-mcp.example.com

请参阅 .env.example，了解所有设置及其注释。

API 版本

GLPI 会在 GET /api.php/ 中列出其提供的高级 API 版本。首次使用时， 服务会读取该列表，并在每个请求路径中固定一个版本 （/api.php/v2.3/... 或 /api.php/v3.0/...），因为 GLPI 会静默地将未知版本路由到最新版本。

GLPI	提供的版本	GLPI_API_VERSION=auto 选择
10.x, 11.0.0-11.0.5	无 / 2.0-2.2	不支持
11.0.6+	2.3	2.3
12.x	2.3, 3.0	3.0

设置 GLPI_API_VERSION=2.3，可让 GLPI 12 继续使用 2.3 架构（例如，在迁移其他集成期间）。 依赖架构差异的工具会兼容两种版本：知识库文章在 2.3 中归入 categories，在 3.0 中则归入父级文章（parents）。

实体和配置文件

GLPI 会将每个 API 会话限定在一个活动配置文件和实体范围内。默认使用用户的默认设置。 GLPI_ENTITY、GLPI_ENTITY_RECURSIVE 和 GLPI_PROFILE 会在每个请求中分别发送 GLPI-Entity、GLPI-Entity-Recursive 和 GLPI-Profile 标头，以更改这些设置。glpi_whoami 会显示当前启用的配置文件和实体， glpi_get_entity_tree 会列出可用实体。

🧰 可用工具

服务端和会话

• glpi_server_info：GLPI 提供的 API 版本、固定的版本、身份验证模式和安全模式
• glpi_whoami：工具所用的 GLPI 用户，以及当前启用的配置文件和实体
• glpi_get_entity_tree：当前用户可操作的实体

工单、更改与问题

均可使用 itil_type：Ticket（默认）、Change 或 Problem。

• glpi_search_itil：按状态、类型、优先级、类别、实体、日期、文本或筛选条件搜索
• glpi_get_itil：获取单个项目及其描述和团队
• glpi_get_itil_timeline：查看跟进、任务、解决方案、审批和文档
• glpi_create_itil / glpi_update_itil / glpi_delete_itil：创建、更新、删除
• glpi_add_itil_followup：添加跟进（公开或私密）
• glpi_add_itil_task：添加任务，并指定状态、耗时、技术人员和计划
• glpi_add_itil_solution：添加解决方案
• glpi_request_itil_validation：请求用户或群组批准工单或更改
• glpi_list_itil_team：查看请求者、负责人和观察者
• glpi_add_itil_team_member / glpi_remove_itil_team_member：分配或移除用户、群组和供应商

资产

• glpi_list_asset_types：列出此 GLPI 的资产类型，包括自定义资产
• glpi_search_assets：按名称、序列号、资产编号或筛选条件搜索一种或所有资产类型
• glpi_get_asset：获取单个资产，可选包含财务信息
• glpi_create_asset / glpi_update_asset / glpi_delete_asset：创建、更新、删除

用户、群组、实体与配置文件

• glpi_search_users / glpi_get_user：查找用户；按 ID 或登录名获取单个用户
• glpi_search_groups / glpi_get_group：查找群组；按 ID 获取单个群组
• glpi_search_entities / glpi_get_entity：查找实体；按 ID 获取单个实体
• glpi_list_profiles：列出配置文件（权限集合）

知识库

• glpi_search_kb_articles / glpi_get_kb_article：搜索和阅读文章
• glpi_create_kb_article / glpi_update_kb_article：创建和更新文章
• glpi_list_kb_categories：列出类别（API 2.3），或顶层文章（API 3.0）

文档

• glpi_search_documents / glpi_get_document：查找文档并读取其元数据
• glpi_download_document：下载文件（文本文件，或以 base64 格式下载二进制文件）

High-Level API 不支持文件上传，因此需要通过 GLPI 本身上传文档。

通用

• glpi_list_endpoints：列出 GLPI OpenAPI 文档中的所有端点路径及其方法
• glpi_describe_schema：查看筛选和写入所用架构的属性、类型和枚举值
• glpi_list_items：列出任意集合，并支持筛选、排序、分页和字段选择
• glpi_get_item：获取任意项目或资源
• glpi_create_item / glpi_update_item / glpi_delete_item：对任意端点执行写入
• glpi_graphql_query：只读 GraphQL 查询（需要 graphql 作用域）

筛选

列表工具接受 filters（会转换为 GLPI 的 RSQL 的字典）和 filter（原始 RSQL）。 两者会以 AND 组合：

{
  "filters": {"status.id": [1, 2], "name__ilike": "*printer*", "entity.id": 0},
  "filter": "priority=ge=4"
}

后缀：__ne、__in、__out、__lt、__le、__gt、__ge、__like、 __ilike（* 为通配符）、__isnull、__isnotnull、__empty、 __notempty。列表表示“匹配任意一项”；None 表示“为空”。嵌套属性 使用点号路径（status.id、entity.id）。glpi_describe_schema 会列出 各架构的属性。计算属性（例如工单的 team）无法用于筛选；GLPI 会返回 HTTP 500。

🔐 MCP 客户端身份验证

了解 MCP 客户端如何向此服务进行身份验证（HTTP 传输），以及工具随后在 GLPI 中以谁的身份操作。请选择一种方式：

模式	设置	MCP 客户端发送	工具以此身份操作
无	-	无	GLPI_USERNAME
静态 bearer 令牌	MCP_HTTP_BEARER_TOKEN	共享令牌	GLPI_USERNAME
OIDC	OIDC_*	使用你的身份提供商进行 OAuth 登录	GLPI_USERNAME
GLPI 登录	GLPI_OAUTH_LOGIN=true	使用其 GLPI 账号进行 OAuth 登录	每位用户各自的身份
令牌透传	GLPI_TOKEN_PASSTHROUGH=true	各自的 GLPI 访问令牌	每位用户各自的身份

用户级模式（GLPI 登录和令牌透传）不能彼此组合使用，也不能与 OIDC 或 MCP_HTTP_BEARER_TOKEN 组合使用；否则服务将拒绝启动。

GLPI 登录：用户使用 GLPI 登录

许多 MCP 客户端（Claude、Open WebUI、远程连接器）只能通过支持动态客户端注册的 OAuth 进行身份验证。启用 GLPI_OAUTH_LOGIN=true 后，服务会提供该 OAuth 接口，并通过 FastMCP 的 OAuthProxy 将请求转发给 GLPI 自带的 OAuth 服务（/api.php/authorize、/api.php/token）。用户在此服务的授权页面上批准 MCP 客户端，在 GLPI 登录页面上登录，然后在 GLPI 的“想要访问您的 GLPI 账户”页面上点击 接受。之后，每次工具调用都会使用该用户自己的 GLPI 令牌、权限和实体。访问令牌过期时，将使用 GLPI 刷新令牌。

1. 在 GLPI 中的 OAuth 客户端设置中，允许 Authorization Code 授权类型和 api、user 作用域，并将重定向 URI 设置为 GLPI_OAUTH_BASE_URL + GLPI_OAUTH_REDIRECT_PATH，例如 https://glpi-mcp.example.com/auth/callback。
2. 配置服务：

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0
GLPI_URL=https://glpi.example.com
GLPI_CLIENT_ID=your-client-id
GLPI_CLIENT_SECRET=your-client-secret
GLPI_OAUTH_LOGIN=true
# Public HTTPS URL of this server
GLPI_OAUTH_BASE_URL=https://glpi-mcp.example.com
# Optional
GLPI_OAUTH_REDIRECT_PATH=/auth/callback
GLPI_OAUTH_ALLOWED_REDIRECT_URIS=https://claude.ai/*,https://openwebui.example.com/*

无需设置 GLPI_USERNAME 和 GLPI_PASSWORD。GLPI_OAUTH_ALLOWED_REDIRECT_URIS 用于限制哪些 MCP 客户端可以完成此流程；若不设置，则接受客户端注册的任何重定向 URI。

令牌透传

启用 GLPI_TOKEN_PASSTHROUGH=true 后，每个 MCP 客户端都会通过 Authorization: Bearer <token> 发送自己的 GLPI OAuth 访问令牌。服务会向 GLPI 验证该令牌（GET /session，缓存 1 分钟），并在每次调用时转发该令牌，因此每个客户端都会以自己的 GLPI 用户身份运行。服务自身的凭据绝不会被使用。客户端负责获取和刷新自己的令牌。

OIDC / OAuth 身份验证（可选）

对于 OAuth 专用的 MCP 客户端，如果工具应以同一个服务账户运行，服务可以使用 FastMCP 的 OIDCProxy，在现有 OIDC 身份提供商（Authentik、Keycloak、PocketID、Auth0、Entra ID 等）前提供 OAuth 接口。GLPI 凭据不会传递给客户端。

在身份提供商中创建一个机密客户端，并将重定向 URI 设置为 OIDC_BASE_URL + OIDC_REDIRECT_PATH，例如 https://glpi-mcp.example.com/auth/callback。

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8000

# All four are required to enable OIDC
OIDC_CONFIG_URL=https://id.example.com/.well-known/openid-configuration
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
# Public URL where this server is reachable (HTTPS except on localhost)
OIDC_BASE_URL=https://glpi-mcp.example.com

# Optional settings
OIDC_REDIRECT_PATH=/auth/callback
OIDC_REQUIRED_SCOPES=openid,profile
OIDC_ALLOWED_REDIRECT_URIS=https://example.com/*
OIDC_VERIFY_ID_TOKEN=false
OIDC_FORWARD_RESOURCE=false

OIDC 配置不完整时会忽略该配置，并发出警告。配置 OIDC 后，它的优先级高于 MCP_HTTP_BEARER_TOKEN。

• OIDC_VERIFY_ID_TOKEN=true 会验证 id_token，而不是访问令牌，适用于签发不透明访问令牌的身份提供商。
• 默认情况下，OIDC_FORWARD_RESOURCE 处于关闭状态，因为不支持 RFC 8707 的身份提供商会以 invalid_request 拒绝授权请求。

持久化 OAuth 状态

使用 GLPI 登录或 OIDC 时，客户端注册信息和加密令牌会存储在 FastMCP 的数据目录中。如果该目录不持久化，每次重启都会要求所有客户端重新注册并登录。Docker 镜像将 FASTMCP_HOME=/data 设为默认值，因此请在此处挂载卷：

docker run -v glpi-mcp-data:/data --env-file .env ghcr.io/mhajder/glpi-mcp:latest

在反向代理后运行

GLPI_OAUTH_BASE_URL / OIDC_BASE_URL 必须是外部可访问的 HTTPS URL，并且代理必须原样转发 Host 标头，否则此服务发布的 OAuth 元数据会指向错误的主机。

🔒 安全与防护功能

只读模式

服务支持只读模式，可隐藏所有写入工具：

READ_ONLY_MODE=true

试运行模式

写入工具仍可用，但只会返回它们将发送的请求（方法、端点和正文）；不会对 GLPI 做任何更改：

DRY_RUN_MODE=true

基于标签筛选工具

你可以设置要禁用的标签，以停用特定类别的工具：

DISABLED_TAGS=assets,knowledgebase,graphql

标签：session、generic、graphql、itil、tickets、assets、administration、users、groups、entities、profiles、knowledgebase、documents、write、read-only。

安全写入

• 如果写入请求已发送，但未收到响应（超时、连接中断），则会报告为可能已应用，绝不会盲目重试。
• 创建操作收到 5xx 响应时不会重试，因为 GLPI 可能已经创建了项目。
• 如果重定向会将写入操作变成 GET 请求，则会报告为未应用。
• 除非指定 force=true，否则删除操作会将项目移至回收站。如果在服务器错误后重试删除操作，并发现项目已不存在，则会报告为已删除。
• GLPI_TIMEOUT 是单次请求的总超时时间：版本查询、令牌、请求及其重试共用此时间。
• 通用工具会拒绝离开 API 或指向 OAuth 端点的端点路径。

响应大小限制

RESPONSE_MAX_SIZE=500000

限制每个工具响应的大小，避免大型列表淹没模型上下文。

大型工具集的工具搜索

对于拥有大量工具的服务，FastMCP 工具搜索可缩短提示词。 启用后，list_tools 会返回两个合成工具：

• search_tools：查找匹配的工具并返回其完整架构
• call_tool：按名称执行任何已发现的工具

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25      # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

工具搜索会遵循现有的可见性控制（只读模式和已禁用的标签）。

速率限制

请求会按客户端使用滑动窗口进行限制。启用按用户访问时，每位 GLPI 用户都有各自的窗口。

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window (default: 60)
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

Sentry 错误跟踪与监控（可选）

服务器可选支持 Sentry，用于错误跟踪和性能监控。安装可选依赖：

uv sync --extra sentry

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/6789

# Optional settings
SENTRY_TRACES_SAMPLE_RATE=1.0
# When true, tool inputs and outputs (ticket contents, users...) are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.2.3
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
SENTRY_PROFILE_LIFECYCLE=trace
SENTRY_ENABLE_LOGS=true

如果未设置 SENTRY_DSN，则不会收集监控数据。

SSL/TLS 配置

GLPI_VERIFY_SSL=true    # Verify GLPI's certificate against the system trust store
GLPI_TIMEOUT=30         # Total seconds for one request, retries included

传输配置

STDIO 传输（默认）

MCP_TRANSPORT=stdio

HTTP SSE 传输（服务器发送事件）

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8000
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

HTTP Streamable 传输

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8000
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

curl -H "Authorization: Bearer your-secret-token" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:8000/mcp

健康检查端点

两种 HTTP 传输（sse 和 http）均提供 GET /health，服务器能够处理请求时会返回 200 ok。 该端点无需 bearer 令牌或 OAuth 登录，也不会联系 GLPI，因此 GLPI 中断不会导致 MCP 服务被标记为不健康。 Docker 镜像的 HEALTHCHECK 会使用此端点：

curl http://localhost:8000/health

有关 FastMCP 传输的更多信息，请参阅 FastMCP 文档。

🤝 参与贡献

欢迎贡献。开发环境设置、检查和提交消息格式请参阅 CONTRIBUTING.md，报告 bug 和提出功能请求请使用问题模板。

发现安全问题？请按照 SECURITY.md 中的说明私下报告。

📜 许可证

MIT 许可证——详情请参阅 LICENSE。