bugzilla-mcp

Bugzilla のチケットとプロジェクトを管理するための MCP (Model Context Protocol) サーバーです。Express 上で提供され、スケジュールに従って Bugzilla に ping を送る組み込みの cron ジョブを備えています。

Bugzilla 5.2 REST API を対象としています。

特徴

• Streamable HTTP 上の MCP — POST /mcp (ステートレス。あらゆる MCP クライアントで動作)

• 15 のツール — バグ、コメント、添付ファイル、製品、コンポーネント、フィールドメタデータをカバー

• Cron ジョブ — 事前設定された時刻に Bugzilla に ping を送り、新規・変更されたバグをポーリング

• 送信 Webhook — cron ジョブが署名付きの bug.created / bug.changed イベントを設定可能な URL に POST 送信

• 設定ページ — 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 クライアントは http://<host>:3000/mcp にヘッダー Authorization: Bearer <MCP_AUTH_TOKEN> を付けて接続します。

• 設定ページは 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 は、Bugzilla のカスタムフィールド用にオプションの custom_fields オブジェクトを受け入れます。例えば、必須フィールドをフィルタリングまたは設定する際に custom_fields: {"cf_severity_class": "Sev1-Critical"} のように指定します。Bugzilla の REST 契約に従い、複数選択カスタムフィールドの配列値はフィールドの値全体を置き換えます。keywords や cc とは異なり、カスタムフィールドには増分の {add, remove} 形式はありません。

注: Bugzilla にはバグ削除 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 に配置するため、中間プロキシやアクセスログに記録される可能性があります。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 イメージで使用)。ローカルの .env ファイルを読み込むには start:local または dev を使用します。

Cron ジョブ

各スケジュール実行時に、ジョブは:

1. ヘルスチェックとして GET /rest/version を呼び出します。

2. 前回の実行以降に変更されたバグを GET /rest/bug?last_change_time=<lastRun> でポーリングし (初回実行時はベースラインがないためスキップ)、新規バグ (creation_time ≥ 前回実行) と変更バグに分割します。

3. Webhook URL が設定されている場合、Webhook イベントを配信します (下記参照)。

4. 結果をログに記録し、最後の結果をメモリに保存します。GET /cron/status で確認できます。

最後の実行ウォーターマークは STATE_FILE に永続化されるため、サーバーがダウンしている間に登録されたバグを再起動時にスキップすることはありません。ウォーターマークは Webhook の配信が成功した後 (または Webhook が設定されていない場合) にのみ進むため、失敗した配信は次回の実行で再試行されます (at-least-once セマンティクス — 受信側はバグ id で重複排除する必要があります)。

Webhook

WEBHOOK_URL が設定されている場合 (または設定ページで設定された場合)、各 cron 実行はイベントタイプごとに 1 つのバッチ JSON ペイロードを POST 送信します:

{
  "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 も同じ構造です。配信に失敗した場合は指数バックオフ (1秒/5秒/25秒) で 3 回再試行します。最後の配信ステータスは GET /cron/status と設定ページで確認できます。

WEBHOOK_SECRET が設定されている場合、各リクエストには X-Webhook-Signature: sha256=<生ボディの16進HMAC-SHA256> が含まれます。受信側で検証してください。例 (Node.js):

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

Webhook は設定された BUGZILLA_API_KEY の ID に表示可能なバグのみを参照します。アカウントが読み取れないグループ制限付きバグは配信されません。

設定ページ

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 → Preferences → API Keys)。Devin はすべての読み取りと書き込みでこのアカウントとして動作し、バグ履歴にはそのアカウントによる変更として記録されます。

   • インスタンスが Bugzilla 5.0.x の場合は BUGZILLA_AUTH_STYLE=query。

   • MCP_AUTH_TOKEN — ランダムなシークレット (例: openssl rand -hex 32)。Devin だけがサーバーに到達できるようにするために必須です。

3. Devin に MCP サーバーを追加します。 組織管理者は Settings → MCP Marketplace → Add a custom MCP から追加できます (Devin MCP ドキュメント を参照)。エンタープライズ管理者は代わりに Settings → Enterprise → Connections → Server catalog から複数の組織に対して一度設定できます (下図参照)。いずれの場合も、以下を入力します:

   • Transport: HTTP (Streamable HTTP。このサーバーは stdio をサポートしていません)

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

   • Authentication / custom headers: Authorization: Bearer <MCP_AUTH_TOKEN> (値は書き込み専用 — 変更時はすべてのヘッダーを再入力)

   • Enable in sessions はオンのままにし、(エンタープライズカタログのみ) Targeting でサーバーを受け取る組織を選択します。

   

4. 確認します。 Devin に Bugzilla ツールの一覧表示を依頼するか、簡単な search_bugs 呼び出しを実行します。15 個すべてのツール (バグの検索/作成/更新、コメント、添付ファイル、履歴、カスタムフィールド) が利用可能であるはずです。

5. 任意 — Webhook。 https://<your-host>/settings を開き、同じ MCP_AUTH_TOKEN を入力し、ポーリング間隔と Webhook URL を設定すると、サーバーが bug.created / bug.changed イベントをプッシュします (たとえば、新しいバグごとに Devin セッションをトリガーするエンドポイントなど)。

注意:

• 1 つのサーバーインスタンス = 1 つの Bugzilla ID。異なる呼び出し元に異なる権限が必要な場合は、API キーごとに 1 つのインスタンスを実行します。

• .env をコミットしないでください。API キーとトークンはシークレットとして保存します。