bugzilla-mcp

Servidor MCP (Model Context Protocol) para gestionar tickets y proyectos de Bugzilla, servido sobre Express con una tarea cron integrada que hace ping a Bugzilla según una programación.

Orientado a la Bugzilla 5.2 REST API.

Características

• MCP sobre Streamable HTTP en POST /mcp (sin estado; funciona con cualquier cliente MCP)

• 15 herramientas que cubren bugs, comentarios, adjuntos, productos, componentes y metadatos de campos

• Tarea cron que hace ping a Bugzilla a una hora preconfigurada y sondea bugs nuevos y modificados

• Webhook saliente: la tarea cron envía por POST eventos firmados bug.created / bug.changed a una URL configurable

• Página de ajustes en GET /settings para configurar la programación cron y el webhook desde el navegador

• Dockerizado (build multi-etapa, usuario no root, docker-compose)

Related MCP server: kanban-mcp

Inicio rápido

Requiere Node.js 20+ y acceso de red a tu instancia de Bugzilla.

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

Edita .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>

Luego inícialo:

npm run start:local

• Los clientes MCP se conectan a http://<host>:3000/mcp con la cabecera Authorization: Bearer <MCP_AUTH_TOKEN>.

• La página de ajustes está en http://<host>:3000/settings (introduce el mismo token).

• Los ajustes de cron/webhook se guardan en .bugzilla-mcp-state.json junto a la aplicación (sobrescribe la ruta con STATE_FILE).

Para producción: usa una cuenta de servicio de Bugzilla dedicada con privilegios mínimos para la clave de API, establece siempre MCP_AUTH_TOKEN (sin él se rechazan las escrituras de ajustes) y termina TLS delante del servidor si es accesible más allá de localhost.

Herramientas MCP

search_bugs, create_bug y update_bug aceptan un objeto custom_fields opcional para los campos personalizados de Bugzilla, como custom_fields: {"cf_severity_class": "Sev1-Critical"} al filtrar o establecer un campo obligatorio. Según el contrato REST de Bugzilla, un valor de array para un campo personalizado de selección múltiple reemplaza el valor completo del campo; a diferencia de keywords y cc, los campos personalizados no tienen una forma incremental {add, remove}.

Nota: Bugzilla no tiene API de borrado de bugs; el cierre/resolución se hace mediante update_bug (p. ej. status=RESOLVED, resolution=FIXED).

Endpoints HTTP

/mcp, /cron/* y la API JSON de /settings requieren Authorization: Bearer <MCP_AUTH_TOKEN> cuando MCP_AUTH_TOKEN está establecido. La propia página de ajustes es HTML estático; pide el token y lo envía como cabecera Bearer en cada llamada a la API.

Configuración

Copia .env.example a .env y rellénalo:

Los valores cambiados a través de la página de ajustes se persisten en STATE_FILE y sobrescriben las variables de entorno correspondientes al reiniciar.

La clave de API se envía en cada solicitud a Bugzilla como cabecera X-BUGZILLA-API-KEY, o como parámetro de consulta api_key cuando BUGZILLA_AUTH_STYLE=query.

BUGZILLA_AUTH_STYLE=query coloca la clave en la URL de la solicitud, donde los proxies intermedios y los registros de acceso pueden registrarla. Bugzilla 5.0.x ignora la cabecera y no acepta otra autenticación, así que usa query solo para esas instancias, con una cuenta de servicio dedicada de privilegios mínimos y rotación periódica de claves.

Ejecución

Docker (recomendado)

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

Local

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

npm start lee la configuración únicamente del entorno del proceso (usado en la imagen Docker); usa start:local o dev para cargar un archivo .env local.

Tarea cron

En cada tick programado, la tarea:

1. Llama a GET /rest/version como comprobación de salud.

2. Consulta GET /rest/bug?last_change_time=<lastRun> para obtener los bugs modificados desde la ejecución anterior (se omite en la primera ejecución porque no hay línea base) y los divide en bugs nuevos (creation_time ≥ última ejecución) y bugs modificados.

3. Entrega los eventos de webhook (ver más abajo) cuando hay una URL de webhook configurada.

4. Registra los resultados y guarda el último resultado en memoria, visible en GET /cron/status.

La marca de agua de la última ejecución se persiste en STATE_FILE, de modo que un reinicio no omite bugs registrados mientras el servidor estaba caído. La marca de agua solo avanza después de que la entrega del webhook tenga éxito (o cuando no hay webhook configurado), por lo que las entregas fallidas se reintentan en la siguiente ejecución (semántica al menos una vez: los receptores deben deduplicar por id de bug).

Webhook

Cuando WEBHOOK_URL está establecido (o configurado a través de la página de ajustes), cada ejecución del cron envía por POST una carga útil JSON agrupada por tipo de evento:

{
  "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 usa la misma forma. Las entregas fallidas se reintentan 3 veces con retroceso exponencial (1s/5s/25s); el último estado de entrega es visible en GET /cron/status y en la página de ajustes.

Si WEBHOOK_SECRET está establecido, cada solicitud lleva X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>. Verifícala en el receptor, p. ej. en Node:

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

El webhook solo ve bugs visibles para la identidad configurada de BUGZILLA_API_KEY: los bugs restringidos por grupo que la cuenta no puede leer nunca se entregan.

Página de ajustes

GET /settings sirve una página HTML simple (sin paso de compilación, sin framework) para:

• ver y editar el intervalo de sondeo en minutos (convertido a una expresión cron y aplicado en vivo),

• establecer la URL del webhook, el secreto (solo escritura: nunca se muestra de nuevo) y el indicador de habilitado,

• activar Run now y Send test event,

• inspeccionar la última ejecución y el último estado de entrega del webhook.

Introduce el MCP_AUTH_TOKEN en la parte superior de la página; sin él, la API JSON rechaza todas las llamadas. Los cambios se persisten en STATE_FILE (escrito con modo 0600).

Conexión de un cliente MCP

Apunta cualquier cliente MCP compatible con Streamable HTTP a http://<host>:3000/mcp, con la cabecera Authorization: Bearer <MCP_AUTH_TOKEN> si está configurada.

Configuración con Devin

Para permitir que Devin use este servidor como integración MCP:

1. Despliega el servidor en un lugar al que Devin pueda acceder. Devin se ejecuta en la nube, por lo que localhost en tu portátil no funcionará: alójalo en un servidor con una URL HTTPS pública (o VPN/lista blanca). Usa la configuración de Docker anterior o npm run start:local detrás de un proxy inverso que termine TLS.

2. Configura el servidor con tus credenciales de Bugzilla:

   • BUGZILLA_BASE_URL — la URL de tu instancia de Bugzilla.

   • BUGZILLA_API_KEY — una clave de API para una cuenta de servicio dedicada con privilegios mínimos (Bugzilla → Preferences → API Keys). Devin actuará como esta cuenta en cada lectura y escritura, y el historial de bugs atribuirá los cambios a ella.

   • BUGZILLA_AUTH_STYLE=query si la instancia es Bugzilla 5.0.x.

   • MCP_AUTH_TOKEN — un secreto aleatorio (p. ej. openssl rand -hex 32); necesario para que solo Devin pueda acceder al servidor.

3. Añade el servidor MCP en Devin. Los administradores de organización pueden añadirlo mediante Settings → MCP Marketplace → Add a custom MCP (consulta la documentación de MCP de Devin); los administradores de empresa pueden configurarlo una vez para varias organizaciones mediante Settings → Enterprise → Connections → Server catalog, como se muestra a continuación. En cualquier caso, introduce:

   • Transport: HTTP (Streamable HTTP; este servidor no soporta stdio)

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

   • Authentication / custom headers: Authorization: Bearer <MCP_AUTH_TOKEN> (los valores son de solo escritura: vuelve a introducir cada cabecera al cambiarlos)

   • Deja Enable in sessions activado y (solo en el catálogo de empresa) elige qué organizaciones reciben el servidor en Targeting.

   

4. Verifica. Pide a Devin que liste las herramientas de Bugzilla o que ejecute una llamada rápida search_bugs. Las 15 herramientas (buscar/crear/actualizar bugs, comentarios, adjuntos, historial, campos personalizados) deberían estar disponibles.

5. Opcional — webhooks. Abre https://<your-host>/settings, introduce el mismo MCP_AUTH_TOKEN, establece el intervalo de sondeo y una URL de webhook para que el servidor envíe eventos bug.created / bug.changed (por ejemplo, a un endpoint que inicie una sesión de Devin para cada bug nuevo).

Notas:

• Una instancia de servidor = una identidad de Bugzilla. Si diferentes llamadores necesitan permisos distintos, ejecuta una instancia por clave de API.

• Nunca hagas commit de .env; guarda la clave de API y el token como secretos.