bugzilla-mcp

MCP-Server (Model Context Protocol) zur Verwaltung von Bugzilla-Tickets und -Projekten, bereitgestellt über Express mit einem integrierten Cron-Job, der Bugzilla planmäßig anpingt.

Zielt auf die Bugzilla 5.2 REST API ab.

Funktionen

• MCP über Streamable HTTP unter POST /mcp (zustandslos; funktioniert mit jedem MCP-Client)

• 15 Tools für Bugs, Kommentare, Anhänge, Produkte, Komponenten und Feldmetadaten

• Cron-Job, der Bugzilla zu einer vorkonfigurierten Zeit anpingt und nach neuen und geänderten Bugs pollt

• Ausgehender Webhook – der Cron-Job sendet signierte bug.created-/bug.changed-Ereignisse per POST an eine konfigurierbare URL

• Einstellungsseite unter GET /settings zum Konfigurieren des Cron-Zeitplans und des Webhooks über den Browser

• Dockerisiert (Multi-Stage-Build, Nicht-Root-Benutzer, docker-compose)

Related MCP server: kanban-mcp

Schnellstart

Erfordert Node.js 20+ und Netzwerkzugriff auf Ihre Bugzilla-Instanz.

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

.env bearbeiten:

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>

Dann starten Sie es:

npm run start:local

• MCP-Clients verbinden sich mit http://<host>:3000/mcp und dem Header Authorization: Bearer <MCP_AUTH_TOKEN>.

• Die Einstellungsseite befindet sich unter http://<host>:3000/settings (geben Sie denselben Token ein).

• Cron-/Webhook-Einstellungen werden in .bugzilla-mcp-state.json neben der App gespeichert (Pfad mit STATE_FILE überschreiben).

Für die Produktion: Verwenden Sie für den API-Schlüssel ein dediziertes Bugzilla-Dienstkonto mit minimalen Rechten, setzen Sie immer MCP_AUTH_TOKEN (Schreibzugriffe auf die Einstellungen werden ohne ihn verweigert) und beenden Sie TLS vor dem Server, wenn er über localhost hinaus erreichbar ist.

MCP-Tools

search_bugs, create_bug und update_bug akzeptieren ein optionales custom_fields-Objekt für benutzerdefinierte Bugzilla-Felder, z. B. custom_fields: {"cf_severity_class": "Sev1-Critical"} beim Filtern oder Setzen eines Pflichtfelds. Gemäß dem REST-Vertrag von Bugzilla ersetzt ein Array-Wert für ein Mehrfachauswahl-Benutzerdefiniertes Feld den gesamten Wert des Felds – anders als keywords und cc haben benutzerdefinierte Felder keine inkrementelle {add, remove}-Form.

Hinweis: Bugzilla hat keine Delete-Bug-API; Schließen/Auflösen erfolgt über update_bug (z. B. status=RESOLVED, resolution=FIXED).

HTTP-Endpunkte

/mcp, /cron/* und die /settings-JSON-API erfordern Authorization: Bearer <MCP_AUTH_TOKEN>, wenn MCP_AUTH_TOKEN gesetzt ist. Die Einstellungsseite selbst ist statisches HTML; sie fragt nach dem Token und sendet ihn bei jedem API-Aufruf als Bearer-Header.

Konfiguration

Kopieren Sie .env.example nach .env und füllen Sie die Werte aus:

Über die Einstellungsseite geänderte Werte werden in STATE_FILE gespeichert und überschreiben beim Neustart die entsprechenden Umgebungsvariablen.

Der API-Schlüssel wird bei jeder Bugzilla-Anfrage als X-BUGZILLA-API-KEY-Header oder als api_key-Query-Parameter gesendet, wenn BUGZILLA_AUTH_STYLE=query gesetzt ist.

BUGZILLA_AUTH_STYLE=query setzt den Schlüssel in die Anfrage-URL, wo zwischengeschaltete Proxy- und Zugriffsprotokolle ihn aufzeichnen können. Bugzilla 5.0.x ignoriert den Header und akzeptiert keine andere Authentifizierung. Verwenden Sie query daher nur für diese Instanzen, mit einem dedizierten Dienstkonto mit minimalen Rechten und regelmäßiger Schlüsselrotation.

Ausführen

Docker (empfohlen)

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

Lokal

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

npm start liest die Konfiguration nur aus der Prozessumgebung (im Docker-Image verwendet); verwenden Sie start:local oder dev, um eine lokale .env-Datei zu laden.

Cron-Job

Bei jedem geplanten Tick führt der Job Folgendes aus:

1. Ruft GET /rest/version als Health-Check auf.

2. Pollt GET /rest/bug?last_change_time=<lastRun> nach Bugs, die seit dem vorherigen Lauf geändert wurden (beim ersten Lauf übersprungen, da es keine Basislinie gibt), und teilt sie in neue Bugs (creation_time ≥ letzter Lauf) und geänderte Bugs auf.

3. Stellt Webhook-Ereignisse zu (siehe unten), wenn eine Webhook-URL konfiguriert ist.

4. Protokolliert Ergebnisse und speichert das letzte Ergebnis im Speicher, sichtbar unter GET /cron/status.

Das Wasserzeichen des letzten Laufs wird in STATE_FILE gespeichert, sodass ein Neustart keine Bugs überspringt, die während des Serverausfalls gemeldet wurden. Das Wasserzeichen wird nur nach erfolgreicher Webhook-Zustellung (oder wenn kein Webhook konfiguriert ist) weitergeschaltet, sodass fehlgeschlagene Zustellungen beim nächsten Lauf erneut versucht werden (At-least-once-Semantik – Empfänger sollten anhand der Bug-id deduplizieren).

Webhook

Wenn WEBHOOK_URL gesetzt ist (oder über die Einstellungsseite konfiguriert wurde), sendet jeder Cron-Lauf einen gebündelten JSON-Payload pro Ereignistyp per 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 verwendet dieselbe Struktur. Fehlgeschlagene Zustellungen werden dreimal mit exponentiellem Backoff (1s/5s/25s) erneut versucht; der letzte Zustellstatus ist unter GET /cron/status und auf der Einstellungsseite sichtbar.

Wenn WEBHOOK_SECRET gesetzt ist, enthält jede Anfrage X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>. Verifizieren Sie es empfängerseitig, z. B. in Node:

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

Der Webhook sieht nur Bugs, die für die konfigurierte BUGZILLA_API_KEY-Identität sichtbar sind – gruppenbeschränkte Bugs, die das Konto nicht lesen kann, werden nie zugestellt.

Einstellungsseite

GET /settings liefert eine einfache HTML-Seite (kein Build-Schritt, kein Framework), um:

• das Abfrageintervall in Minuten anzuzeigen und zu bearbeiten (in einen Cron-Ausdruck umgewandelt und live angewendet),

• Webhook-URL, Geheimnis (nur schreibbar – wird nie wieder angezeigt) und Aktiviert-Flag zu setzen,

• Run now und Send test event auszulösen,

• den letzten Lauf und den letzten Webhook-Zustellstatus zu prüfen.

Geben Sie den MCP_AUTH_TOKEN oben auf der Seite ein; ohne ihn lehnt die JSON-API jeden Aufruf ab. Änderungen werden in STATE_FILE gespeichert (geschrieben mit Modus 0600).

MCP-Client verbinden

Richten Sie einen beliebigen MCP-Client mit Streamable-HTTP-Unterstützung auf http://<host>:3000/mcp aus, mit Header Authorization: Bearer <MCP_AUTH_TOKEN>, falls konfiguriert.

Einrichtung mit Devin

Damit Devin diesen Server als MCP-Integration nutzen kann:

1. Stellen Sie den Server dort bereit, wo Devin ihn erreichen kann. Devin läuft in der Cloud, daher funktioniert localhost auf Ihrem Laptop nicht – hosten Sie ihn auf einem Server mit einer öffentlichen (oder VPN-/Allowlist-)HTTPS-URL. Verwenden Sie das Docker-Setup oben oder npm run start:local hinter einem TLS-terminierenden Reverse-Proxy.

2. Konfigurieren Sie den Server mit Ihren Bugzilla-Anmeldedaten:

   • BUGZILLA_BASE_URL – die URL Ihrer Bugzilla-Instanz.

   • BUGZILLA_API_KEY – ein API-Schlüssel für ein dediziertes Dienstkonto mit minimalen Rechten (Bugzilla → Einstellungen → API-Schlüssel). Devin wird bei jedem Lese- und Schreibvorgang als dieses Konto agieren, und die Bug-Historie wird Änderungen diesem Konto zuordnen.

   • BUGZILLA_AUTH_STYLE=query, wenn die Instanz Bugzilla 5.0.x ist.

   • MCP_AUTH_TOKEN – ein zufälliges Geheimnis (z. B. openssl rand -hex 32); erforderlich, damit nur Devin den Server erreichen kann.

3. Fügen Sie den MCP-Server in Devin hinzu. Organisations-Admins können ihn über Einstellungen → MCP-Marketplace → Benutzerdefiniertes MCP hinzufügen hinzufügen (siehe die Devin-MCP-Dokumentation); Enterprise-Admins können ihn stattdessen einmalig für mehrere Organisationen über Einstellungen → Enterprise → Verbindungen → Serverkatalog konfigurieren, wie unten gezeigt. Geben Sie in beiden Fällen Folgendes ein:

   • Transport: HTTP (Streamable HTTP; dieser Server unterstützt kein stdio)

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

   • Authentifizierung / benutzerdefinierte Header: Authorization: Bearer <MCP_AUTH_TOKEN> (Werte sind nur schreibbar — bei Änderungen jeden Header erneut eingeben)

   • Lassen Sie In Sitzungen aktivieren aktiviert und wählen Sie (nur Enterprise-Katalog) unter Targeting aus, welche Organisationen den Server erhalten.

   

4. Überprüfen. Bitten Sie Devin, die Bugzilla-Tools aufzulisten oder einen schnellen search_bugs-Aufruf auszuführen. Alle 15 Tools (Bugs suchen/erstellen/aktualisieren, Kommentare, Anhänge, Historie, benutzerdefinierte Felder) sollten verfügbar sein.

5. Optional – Webhooks. Öffnen Sie https://<your-host>/settings, geben Sie denselben MCP_AUTH_TOKEN ein, stellen Sie das Abfrageintervall und eine Webhook-URL ein, damit der Server bug.created-/bug.changed-Ereignisse pusht (z. B. an einen Endpunkt, der für jeden neuen Bug eine Devin-Sitzung auslöst).

Hinweise:

• Eine Serverinstanz = eine Bugzilla-Identität. Wenn verschiedene Aufrufer unterschiedliche Berechtigungen benötigen, führen Sie eine Instanz pro API-Schlüssel aus.

• Committen Sie niemals .env; speichern Sie den API-Schlüssel und den Token als Geheimnisse.