IT Glue

IT Glue MCP 服务

一个模型上下文协议（MCP）服务，可让 Claude 访问 IT Glue 文档和资产管理功能。

一键部署

说明

与其他 Wyre MCP 服务不同，此服务直接调用 IT Glue API， 没有私有的 @wyre-ai/* 运行时依赖，因此一键构建 无需 GitHub Packages 令牌——云端构建器的 npm ci 只会拉取 公共软件包。（只有在安装已发布的 @wyre-ai/itglue-mcp 软件包时才需要 read:packages 令牌；请参阅安装。） DigitalOcean 部署目标会构建完整的 Docker 镜像，并通过 HTTP 运行完整的 MCP 服务， 是推荐的方式；此仓库未提供 Workers 入口文件（src/worker.ts），因此建议使用 DigitalOcean 或预构建容器 镜像（ghcr.io/wyre-ai/itglue-mcp）。

安装

此软件包发布在 GitHub Packages npm 注册表中，即使是公共软件包也需要令牌。 完成一次 npm 身份验证后即可安装：

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/itglue-mcp

仓库的 .npmrc 已将 @wyre-ai 作用域指向 GitHub Packages，并从 NODE_AUTH_TOKEN 读取令牌，因此无需其他配置。npx @wyre-ai/itglue-mcp 也适用相同设置。

或者使用 Docker 镜像：

docker pull ghcr.io/wyre-ai/itglue-mcp:latest

配置

复制 .env.example，并设置以下变量。将该文件中的 CONDUIT_S2S_SECRET 留空；切勿提交真实值。

Variable	Description	Required
ITGLUE_API_KEY	你的 IT Glue API 密钥（格式：ITG.xxx）。供 stdio 使用；当 AUTH_MODE=env 时，也供 HTTP 使用。	是（stdio 和 env 模式）
ITGLUE_JWT	用户会话 JWT，用作可选的回退凭据，供 API 密钥尚无法访问 Document Folders 资源的租户执行文档文件夹操作。请参阅文档文件夹操作的 JWT 回退。	否
ITGLUE_REGION	API 区域：us、eu 或 au（默认值：us）	否
ITGLUE_BASE_URL	覆盖 IT Glue API 基础 URL（高级选项）	否
MCP_TRANSPORT	传输方式：stdio（本地）或 http（远程）。通过 npx/node 运行时默认为 stdio；在 Docker 镜像中默认为 http。	否
MCP_HTTP_PORT	HTTP 传输端口（默认值：8080）	否
MCP_HTTP_HOST	设置了真实 CONDUIT_S2S_SECRET 时的绑定地址。未设置时保留为 0.0.0.0，即历史上容器使用的绑定地址。镜像和 Compose 会在容器内将其设置为 0.0.0.0。	否
AUTH_MODE	env（从环境变量读取凭据；镜像默认值）或 gateway（从 HTTP 请求标头读取每个请求的凭据；Compose 默认值）。Gateway 模式绝不会回退到使用 ITGLUE_*。	否
CONDUIT_S2S_SECRET	HTTP 的服务间密钥。当该值为空或为已知占位值（changeme、secret、replace-me、your-s2s-secret 及其他示例值）时，进程会记录错误并以非零状态退出。使用 openssl rand -hex 32 生成密钥。未设置此值时，Compose 不会启动。该值绝不会被记录。	HTTP 必需
MCP_ALLOW_INSECURE_DEV	仅在本地开发时，准确设置为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、不强制校验 X-Gateway-S2S，且只绑定到 127.0.0.1。设置非回环地址的 MCP_HTTP_HOST 时会拒绝启动。已知占位密钥仍会导致启动失败。	否

/health 和 /healthz 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

当 AUTH_MODE=gateway 时，MCP Gateway 会通过 HTTP 标头而非环境变量，按请求注入凭据。请参阅 HTTP 身份验证和远程部署。

HTTP 身份验证

设置了 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 时，每个 /mcp 请求都必须包含 X-Gateway-S2S。校验逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：标头值的格式为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥，对字面字符串 t=<unix seconds> 计算得到的 HMAC-SHA256（64 位小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。若标头缺失或无效，则在读取供应商凭据之前返回 HTTP 401。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-ITGlue-API-Key: $ITGLUE_API_KEY" \
  -H "X-ITGlue-Region: us" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-ITGlue-API-Key（或 X-API-Key）或 X-ITGlue-JWT。这些标头是该请求唯一的凭据来源。AUTH_MODE=env 仍要求提供已签名的 X-Gateway-S2S 标头，然后使用环境变量中的 ITGLUE_API_KEY 和 ITGLUE_JWT。

文档文件夹操作的 JWT 回退机制

JWT 是可选的——只有当租户的 API 密钥尚无法访问文档文件夹时才需要。所有与文件夹相关的路径都会先尝试使用 API 密钥：

• search_documents — 默认返回包含文件夹的列表（filter[document_folder_id]=null 会返回所有文档，包括归入文件夹的文档；每条结果都包含其 documentFolderId）。如果租户的 API 拒绝此筛选条件，服务端会重试 [ne] 筛选形式，最后降级为旧版仅返回根目录中文档的列表，并在结果中说明这一点。任何环节都不会用到 JWT。
• list_document_folders — IT Glue 的公开（API 密钥）API 现已记录文档文件夹资源，该功能将在 2026 年陆续向各租户推出。服务端会先尝试使用 API 密钥（先通过组织关联路径，再通过顶层 /document_folders 路径），只有密钥被拒绝时才会回退到 JWT。
• create_document — 按名称选择文件夹时，会采用相同的 API 密钥优先枚举方式，然后尝试配置的 JWT；如果两者都无法列出文件夹，则会提示你提供文件夹 URL、同级文档 URL 或数字文件夹 ID，作为最后的手段。

如果确实需要 JWT 回退，请根据部署方式提供：

模式	如何提供 JWT
本地／环境变量（AUTH_MODE=env）	设置 ITGLUE_JWT 环境变量。
远程网关（AUTH_MODE=gateway）	在请求头中发送 X-ITGlue-JWT。
交互式客户端（Claude Desktop/Code）	留空——服务端会在首次使用时提示你粘贴 JWT，并在会话期间缓存。

无头部署（Docker、云端）： 无人可以响应交互式提示，因此，如果租户的 API 密钥无法枚举文件夹，就必须设置 ITGLUE_JWT（env 模式）或发送 X-ITGlue-JWT（gateway 模式），才能进行文件夹枚举。

从浏览器获取 JWT：

1. 在浏览器中登录 IT Glue。
2. 打开 DevTools → Network 选项卡。
3. 点击任意一个发往 itg-api-*.itglue.com 的请求。
4. 复制请求头 Authorization: Bearer <token> 的值——其中的 <token> 部分就是你的 JWT。

有效期： IT Glue 的 JWT 有效期较短（约 2 小时）。在长期运行的容器中设置的 ITGLUE_JWT 会过期，导致 JWT 回退开始失败，直到 JWT 刷新为止。交互式客户端只需在过期时重新提示输入即可。API 密钥操作不受影响。

可用工具

组织

• search_organizations - 搜索组织，可按名称、类型、状态或 PSA ID 进行筛选
• get_organization - 按 ID 获取指定组织

配置项（设备／资产）

• search_configurations - 搜索配置项，可按组织、名称、类型、状态、序列号、RMM ID 或 PSA ID 进行筛选
• get_configuration - 按 ID 获取指定配置项
• archive_configuration - 归档配置项（软删除——将其从常规视图中隐藏，但仍可恢复）。可通过 unarchive_configuration 撤销。通过 PSA/RMM 集成同步的配置项（psaIntegration: enabled / syncActive: true）可能会在下次同步时恢复或更新，因此请先整理源系统（Autotask / Datto RMM）
• unarchive_configuration - 恢复先前归档的配置项，使其重新显示在常规视图中

位置（地址／站点）

• search_locations - 搜索组织的位置（内置的地址／站点记录），可按组织、名称、城市、地区或国家筛选。结果包含地址字段和电话号码。
• get_location - 按 ID 获取指定位置，包括完整地址和电话号码
• create_location - 为组织创建新位置（需要 name，通常还需要 country_id）
• update_location - 更新现有位置；只会更改你提供的字段

密码

• search_passwords - 搜索密码条目（仅包含元数据，不会在结果中显示实际密码）
• get_password - 获取指定的密码条目，包括实际密码值

文档

• search_documents - 搜索文档，可按组织、名称或文件夹筛选。默认列出包含文件夹信息的结果（每条结果都包含其 documentFolderId）；如果租户的 API 拒绝文件夹筛选，则会自动降级为仅列出根目录中的文档
• get_document - 按 ID 获取指定文档，包括其分节正文。在 MCP Apps 主机中会呈现为交互式卡片，参见交互式文档卡片
• list_document_folders - 列出组织的文档文件夹（名称和 ID）。对于 IT Glue 提供 Document Folders 资源的租户，可使用 API 密钥；否则会回退到 JWT，参见文档文件夹操作的 JWT 回退机制
• create_document - 在组织中创建文档，可选择添加正文内容。如果未指定文件夹，会提示选择文件夹；传入 skip_folder_prompt=true 可在组织根目录中创建
• update_document - 重命名文档。只会更改你提供的名称。不支持移动文件夹：IT Glue 的 Documents API 将 document_folder_id 标记为不可用于 PUT/PATCH
• list_document_sections - 编辑前，按顺序列出文档的各个分节
• create_document_section - 添加标题或文本分节。编辑后调用 publish_document
• update_document_section - 替换分节内容。编辑后调用 publish_document
• delete_document_section - ⚠ 永久删除一个分节（不可撤销）。编辑后调用 publish_document
• publish_document - 发布分节更改，使其生效
• archive_document - 软删除文档（从常规视图中隐藏，可通过 unarchive_document 恢复）
• unarchive_document - 恢复先前归档的文档
• delete_document - ⚠ 永久删除文档及其所有分节（不可撤销；如果以后可能还会用到，请优先使用 archive_document）

附件

• create_attachment - 将文件附加到清单、清单模板、配置、联系人、文档、域名、灵活资产、位置、密码、SSL 证书或工单。输入为 Base64。也是向文档正文添加图片的唯一受支持方式，参见文档中的图片
• list_attachments - 列出记录的附件及其下载 URL

灵活资产

• search_flexible_assets - 搜索灵活资产（需要 flexible_asset_type_id）

用户指标

• search_user_metrics - 搜索用户活动指标：按用户、组织和资源类型统计 created / viewed / edited / deleted 操作次数，并按日期分桶。可按 user_id、organization_id、resource_type 和 start_date / end_date 范围筛选；按 id、created、viewed、edited、deleted 或 date 排序（前缀 - 表示降序）。

  这是 IT Glue 用户信誉评分背后的原始数据，因此可以回答“谁确实在维护文档”——按技术人员、客户和资源类型统计。

  日期范围规则（已于 2026-08-06 对照 api.itglue.com 进行实时验证）：

  • 日期范围最多可跨 7 天（结束日期减开始日期）——因此 2026-08-01,2026-08-08（8 个日历日）会被接受，而 2026-08-01,2026-08-09 会返回 422。API 比较的是日期差，而不是包含首尾日期在内的天数；如果把“超过一周”理解为 7 个自然日，就会多算一天，从而错误地拒绝有效查询。
  • end_date 必须与 start_date 一起使用。 IT Glue 会拒绝以通配符开头的筛选条件（*,2026-08-07 → 422），因此仅指定结束日期必定会报错，而不会缩小查询范围。结束日期可以留空（2026-08-01,*）。
  • 两种违规情况都会返回相同的 422 标题——"date range filter cannot be longer than a week, and cannot start with a wildcard"——因此 API 无法告知你具体触发了哪种情况。工具会自行检查并指出原因，不会因此消耗 API 调用。
  • 不指定这两个日期，可由 IT Glue 应用其默认时间范围。

  注意事项 — 未知筛选键会被静默忽略。 filter[not-a-real-key]=x 会返回 HTTP 200 和完整的未筛选结果集，而不是报错（已实时验证）。因此，拼错或记错筛选名称时，查询看起来会成功且范围正确，实际上却会返回所有内容。如果结果看起来过于宽泛，请用一个不可能存在的值交叉核对行数（filter[resource-type]=ZZZNoSuchType 会正确返回 0 行）。

实用工具

• itglue_health_check - 验证与 IT Glue API 的连接

交互式文档卡片（MCP Apps）

在 MCP Apps 宿主（Claude Desktop/web）中，get_document 会以交互式卡片形式呈现，显示文档名称、组织、文件夹、关键日期以及各部分的纯文本预览；在其他宿主中，纯 JSON 行为保持不变。该卡片为只读，默认采用中性色；可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制——无需重新构建。

文档中的图片

将图片插入文档正文时，需要通过附件，而不是图片本身。 已于 2026-08-31 在 api.itglue.com 上进行实时验证：

尝试的操作	结果
在章节 HTML 中内联 <svg>	会被静默移除。 章节保存成功并返回 200，但图表会从存储内容中消失
<img src="data:image/png;base64,…">	返回 500 错误，而非验证错误
POST /documents/{id}/relationships/document_images	404
上传附件，然后使用 <img src="https://…/attachments/{id}"> 引用	可用，并会以内嵌方式呈现

关于这个 404，有一点需要注意，避免过度解读。文档图片是一种真实存在的资源——IT Glue 网页编辑器会创建此类图片，并在章节 HTML 中存储类似 /{org_id}/docs/{doc_id}/images/{image_id} 的相对路径；读取时，渲染器会将其替换为签名 S3 URL。无法找到的是已文档化的公共 API中用于创建图片的路由；编辑器似乎使用的是内部端点。因此，准确的理解是“未找到公共 API 的图片上传路由”，而不是“文档图片不存在”。

因此，应使用 create_attachment：上传文件，然后引用它返回的 downloadUrl。内联 SVG 的情况尤其值得留意，因为它看起来像是写入成功了。

create_attachment(resource_type="documents", resource_id, file_name, content)
→ reference the returned downloadUrl from an <img src> in update_document_section
→ publish_document

请注意，清理器还会移除部分内联样式属性（包括 max-width），因此应将图片调整为所需宽度，而不要依赖 CSS。

传入原始 base64。如果开头保留了 data:...;base64, 前缀，工具会将其移除，而不会原样传递：IT Glue 会存储收到的内容，因此带前缀的负载会“成功”上传，却生成损坏的文件，直到有人打开它才会发现问题。

与 Claude Code 搭配使用

添加到你的 .mcp.json 中：

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["@wyre-ai/itglue-mcp"],
      "env": {
        "ITGLUE_API_KEY": "${ITGLUE_API_KEY}",
        "ITGLUE_REGION": "us"
      }
    }
  }
}

或者使用 Docker（本地 stdio）：

{
  "mcpServers": {
    "itglue": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "ITGLUE_API_KEY",
        "ghcr.io/wyre-ai/itglue-mcp:latest"
      ],
      "env": {
        "ITGLUE_API_KEY": "${ITGLUE_API_KEY}"
      }
    }
  }
}

注意： Docker 镜像默认使用 HTTP 传输。上面的 -e MCP_TRANSPORT=stdio 是将其作为本地 stdio 服务运行以供 Claude Desktop/Code 使用的必需参数。服务端部署请参阅下文的远程部署。

远程部署（HTTP Streamable）

对于服务器/云端部署，请使用 HTTP Streamable 传输运行服务。Docker 镜像已默认将 MCP_TRANSPORT=http 设置为端口 8080，并在容器内监听 0.0.0.0。只有在 CONDUIT_S2S_SECRET 设置为有效密钥后，服务才会启动。除非前面有代理，否则请仅在回环地址上发布端口。提供两个端点：

• POST /mcp — MCP Streamable HTTP 端点（无状态：每个请求都会创建一个全新的服务）。需要有效的 X-Gateway-S2S 标头。请参阅 HTTP 身份验证。
• GET /health 和 GET /healthz — 无需身份验证的运行状况检查，不会读取凭据

环境变量模式（单租户）

S2S 身份验证通过后，凭据从环境变量中读取。适用于一个 API 密钥服务整个部署的情况。镜像默认使用 AUTH_MODE=env。

docker run -d \
  --name itglue-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e ITGLUE_API_KEY="ITG.xxxxxxxx" \
  -e ITGLUE_REGION="us" \
  --restart unless-stopped \
  ghcr.io/wyre-ai/itglue-mcp:latest

# Verify
curl http://127.0.0.1:8080/health
# {"status":"ok","transport":"http","authMode":"env",...}

客户端使用 MCP Streamable HTTP 传输连接到 http://127.0.0.1:8080/mcp，并且必须发送 X-Gateway-S2S。

网关模式（多租户 / 托管）

部署在 MCP 网关（例如 mcp.wyre.ai）之后时，请设置 AUTH_MODE=gateway。此时，凭据会通过 HTTP 请求头按请求注入，而非通过环境变量注入。缺少两种凭据请求头的请求会收到 401，且不会回退到进程环境中的 ITGLUE_API_KEY 或 ITGLUE_JWT。Compose 即为此模式：它不会设置这些变量，也不会使用 env_file，因此项目 .env 无法注入静态供应商凭据。Compose 仍要求设置 CONDUIT_S2S_SECRET。

docker run -d \
  --name itglue-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=gateway \
  --restart unless-stopped \
  ghcr.io/wyre-ai/itglue-mcp:latest

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

网关会在每个请求中提供凭据和 X-Gateway-S2S 证明：

请求头	说明	必需
X-Gateway-S2S	使用 CONDUIT_S2S_SECRET 签名的 t=<unix seconds>,v1=<hex hmac-sha256>。请参阅HTTP 身份验证。	是
X-ITGlue-API-Key（或 X-API-Key）	IT Glue API 密钥	API 密钥或 JWT 二选一
X-ITGlue-JWT	用于提升权限范围操作的 JWT	API 密钥或 JWT 二选一
X-ITGlue-Region	API 区域：us、eu 或 au（默认：us）	否
X-ITGlue-Base-URL	覆盖 IT Glue API 基础 URL	否

同时缺少 X-ITGlue-API-Key 和 X-ITGlue-JWT 的请求会收到 401。在此模式下，/health 端点会报告 "authMode":"gateway"，且不会读取这些请求头。

不使用 Docker 运行

设置 MCP_TRANSPORT=http 后，同一传输方式也可用于已安装 / 已构建的副本。在设置 CONDUIT_S2S_SECRET 之前，服务不会启动：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  MCP_TRANSPORT=http MCP_HTTP_PORT=8080 ITGLUE_API_KEY="ITG.xxxxxxxx" \
  npx @wyre-ai/itglue-mcp

不设置密钥的本地 HTTP 仅用于开发。服务会绑定到 127.0.0.1 并记录警告。将 MCP_HTTP_HOST 设置为非回环地址（包括 0.0.0.0）会导致启动退出：

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 \
  npx @wyre-ai/itglue-mcp

示例查询

配置完成后，你可以向 Claude 提问：

• “在 IT Glue 中搜索包含 ‘Acme’ 的组织”
• “获取设备 ID 12345 的配置详情”
• “查找组织 ID 100 的所有密码”
• “搜索类型为 54321 的灵活资产”

安全说明

• 出于安全考虑，密码搜索结果不包含实际密码值
• 使用 get_password 并指定明确的 ID 来获取密码值
• 使用环境变量或机密管理器安全地存储 API 密钥
• API 密钥应在 IT Glue 中具有适当的读取权限

许可证

Apache-2.0

贡献

请参阅CONTRIBUTING.md了解指南。