bugzilla-mcp

MCP（Model Context Protocol）服务器，用于管理 Bugzilla 工单和项目， 基于 Express 提供服务，并内置一个按计划 ping Bugzilla 的 cron 任务。

目标为 Bugzilla 5.2 REST API。

功能

• 基于 Streamable HTTP 的 MCP，位于 POST /mcp（无状态；适用于任何 MCP 客户端）

• 15 个工具，涵盖 bug、评论、附件、产品、组件和字段元数据

• Cron 任务，在预配置的时间 ping Bugzilla，并轮询新增和变更的 bug

• 出站 Webhook — cron 任务将带签名的 bug.created / bug.changed 事件 POST 到可配置的 URL

• 设置页面，位于 GET /settings，可在浏览器中配置 cron 计划和 webhook

• Docker 化（多阶段构建、非 root 用户、docker-compose）

Related MCP server: kanban-mcp

快速开始

需要 Node.js 20+ 以及到你的 Bugzilla 实例的网络访问。

git clone https://github.com/COG-GTM/bugzilla-mcp
cd bugzilla-mcp
npm install
npm run build
cp .env.example .env

编辑 .env：

BUGZILLA_BASE_URL=https://your-bugzilla.example.com/
BUGZILLA_API_KEY=<key from Bugzilla Preferences -> API Keys>
# Only for Bugzilla 5.0.x, which ignores the auth header (default: header):
BUGZILLA_AUTH_STYLE=query
# Any random string of your choosing, e.g. `openssl rand -hex 32`:
MCP_AUTH_TOKEN=<random token>

然后启动它：

npm run start:local

• MCP 客户端通过请求头 Authorization: Bearer <MCP_AUTH_TOKEN> 连接到 http://<host>:3000/mcp。

• 设置页面位于 http://<host>:3000/settings（输入相同的令牌）。

• Cron/webhook 设置持久化在应用旁边的 .bugzilla-mcp-state.json 中 （可通过 STATE_FILE 覆盖路径）。

生产环境：为 API 密钥使用专用的最小权限 Bugzilla 服务账户， 始终设置 MCP_AUTH_TOKEN（未设置时拒绝写入设置）， 并且如果服务器可从 localhost 之外访问，请在其前面终止 TLS。

MCP 工具

search_bugs、create_bug 和 update_bug 接受一个可选的 custom_fields 对象，用于 Bugzilla 自定义字段，例如在过滤或设置必填字段时使用 custom_fields: {"cf_severity_class": "Sev1-Critical"}。根据 Bugzilla 的 REST 约定， 多选自定义字段的数组值会替换该字段的整个值——与 keywords 和 cc 不同， 自定义字段没有增量的 {add, remove} 形式。

注意：Bugzilla 没有删除 bug 的 API；关闭/解决通过 update_bug 完成 （例如 status=RESOLVED、resolution=FIXED）。

HTTP 端点

当设置了 MCP_AUTH_TOKEN 时，/mcp、/cron/* 和 /settings JSON API 需要 Authorization: Bearer <MCP_AUTH_TOKEN>。设置页面本身是静态 HTML； 它会在页面顶部请求令牌，并在每次 API 调用时将其作为 Bearer 请求头发送。

配置

将 .env.example 复制为 .env 并填写：

通过设置页面更改的值会持久化到 STATE_FILE 中，并在重启时覆盖相应的环境变量。

API 密钥会在每个 Bugzilla 请求中作为 X-BUGZILLA-API-KEY 请求头发送， 或者在 BUGZILLA_AUTH_STYLE=query 时作为 api_key 查询参数发送。

BUGZILLA_AUTH_STYLE=query 会将密钥放入请求 URL，中间代理和访问日志可能会记录该 URL。 Bugzilla 5.0.x 会忽略请求头且不接受其他身份验证方式，因此请仅对这些实例使用 query， 并使用专用的最小权限服务账户和定期轮换密钥。

运行

Docker（推荐）

cp .env.example .env   # then edit
docker compose up --build

本地

npm install
npm run build
npm run start:local   # loads .env via node --env-file; or: npm run dev

npm start 仅从进程环境读取配置（用于 Docker 镜像）； 使用 start:local 或 dev 来加载本地 .env 文件。

Cron 任务

在每个计划时间点，任务会：

1. 调用 GET /rest/version 作为健康检查。

2. 轮询 GET /rest/bug?last_change_time=<lastRun> 以获取自上次运行以来被修改的 bug （首次运行跳过，因为没有基线），并将其分为新 bug（creation_time ≥ 上次运行）和已变更的 bug。

3. 当配置了 webhook URL 时，投递 webhook 事件（见下文）。

4. 记录结果并将上次结果存储在内存中，可在 GET /cron/status 查看。

上次运行的水位线持久化在 STATE_FILE 中，因此重启不会跳过服务器停机期间提交的 bug。 水位线仅在 webhook 投递成功（或未配置 webhook）后才会前进，因此失败的投递会在下次运行时重试 （至少一次语义——接收方应按 bug id 去重）。

Webhook

当设置了 WEBHOOK_URL（或通过设置页面配置）时，每次 cron 运行会按事件类型 POST 一个批量的 JSON 负载：

{
  "event": "bug.created",
  "instance": "https://bugzilla.example.com",
  "firedAt": "2026-01-01T09:00:00.000Z",
  "bugs": [
    { "id": 17, "summary": "...", "status": "CONFIRMED",
      "creation_time": "...", "last_change_time": "..." }
  ]
}

bug.changed 使用相同的结构。失败的投递会以指数退避（1s/5s/25s）重试 3 次； 上次投递状态可在 GET /cron/status 和设置页面上查看。

如果设置了 WEBHOOK_SECRET，每个请求都会携带 X-Webhook-Signature: sha256=<原始请求体的十六进制 HMAC-SHA256>。请在接收方验证它， 例如在 Node 中：

const expected = "sha256=" +
  crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

Webhook 只能看到配置的 BUGZILLA_API_KEY 身份可见的 bug—— 该账户无法读取的受组限制的 bug 永远不会被投递。

设置页面

GET /settings 提供一个纯 HTML 页面（无需构建步骤，无框架），用于：

• 查看和编辑以分钟为单位的轮询间隔（转换为 cron 表达式并实时生效），

• 设置 webhook URL、密钥（只写——永远不会回显）和启用标志，

• 触发 立即运行 和 发送测试事件，

• 查看上次运行和上次 webhook 投递状态。

在页面顶部输入 MCP_AUTH_TOKEN；没有它，JSON API 会拒绝所有调用。 更改会持久化到 STATE_FILE（以 0600 权限写入）。

连接 MCP 客户端

将任何支持 Streamable HTTP 的 MCP 客户端指向 http://<host>:3000/mcp， 如果已配置，则带上请求头 Authorization: Bearer <MCP_AUTH_TOKEN>。

与 Devin 一起设置

要让 Devin 将此服务器用作 MCP 集成：

1. 将服务器部署到 Devin 可以访问的位置。 Devin 在云端运行， 因此你笔记本电脑上的 localhost 无法使用——请将其托管在具有公共 （或 VPN/白名单）HTTPS URL 的服务器上。使用上面的 Docker 配置， 或使用 TLS 终止反向代理后面的 npm run start:local。

2. 使用你的 Bugzilla 凭据配置服务器：

   • BUGZILLA_BASE_URL — 你的 Bugzilla 实例 URL。

   • BUGZILLA_API_KEY — 用于专用最小权限服务账户的 API 密钥 （Bugzilla → 偏好设置 → API 密钥）。Devin 将以此账户身份执行所有读写操作， bug 历史会将变更归因于该账户。

   • 如果实例是 Bugzilla 5.0.x，则设置 BUGZILLA_AUTH_STYLE=query。

   • MCP_AUTH_TOKEN — 一个随机密钥（例如 openssl rand -hex 32）； 必须设置，以确保只有 Devin 可以访问服务器。

3. 在 Devin 中添加 MCP 服务器。 组织管理员可以通过 设置 → MCP 市场 → 添加自定义 MCP 添加（参见 Devin MCP 文档）；企业 管理员也可以通过 设置 → 企业 → 连接 → 服务器目录 为多个组织一次性配置， 如下所示。无论哪种方式，都需要填写：

   • 传输方式：HTTP（Streamable HTTP；此服务器不支持 stdio）

   • URL：https://<your-host>/mcp

   • 身份验证 / 自定义请求头： Authorization: Bearer <MCP_AUTH_TOKEN>（值只写——更改时需要重新输入每个请求头）

   • 保持 在会话中启用 为开启状态，并且（仅限企业目录）在 目标 下选择 接收该服务器的组织。

   

4. 验证。 让 Devin 列出 Bugzilla 工具，或运行一次快速的 search_bugs 调用。所有 15 个工具（搜索/创建/更新 bug、评论、 附件、历史、自定义字段）都应可用。

5. 可选 — Webhook。 打开 https://<your-host>/settings，输入相同的 MCP_AUTH_TOKEN，设置轮询间隔和 webhook URL，让服务器推送 bug.created / bug.changed 事件（例如，推送到一个为每个新 bug 触发 Devin 会话的端点）。

注意：

• 一个服务器实例 = 一个 Bugzilla 身份。如果不同的调用者需要不同的权限， 请为每个 API 密钥运行一个实例。

• 切勿提交 .env；将 API 密钥和令牌作为机密存储。