jira-alerts-mcp

Jira Alerts MCP

Encuentra qué te está paginando y quién está de guardia — desde tu agente.

Un servidor MCP para Jira Service Management Operations — la superficie de alertas que reemplazó a Opsgenie, que ningún otro servidor MCP de Jira cubre.

Busca alertas y lee sus notas y línea de tiempo de actividad; reconoce, cierra, anota y añade respondedores; y consulta quién está de guardia ahora y después. Doce herramientas, cuatro de ellas de escritura.

Demo

Tres preguntas en una sola sesión, contra un sitio JSM en vivo: quién está de guardia, qué está abierto, y reconoce lo que no lo está. Observa especialmente la última respuesta — el agente confirma que el reconocimiento realmente se registró (ack landed 16:38:00.577Z) en lugar de asumirlo, que es el comportamiento de escritura asíncrona descrito en Qué maneja este servidor por ti.

Inicio rápido

Necesitas Node ≥ 24 y un sitio Atlassian Cloud con JSM Operations habilitado. No hay nada que clonar ni compilar — tu cliente MCP ejecuta el paquete publicado.

1. Encuentra tu cloud id. Abre esto mientras estás conectado a tu sitio:

https://<your-site>.atlassian.net/_edge/tenant_info

Responde con una línea — {"cloudId":"..."} — y ese UUID es lo que JSM_CLOUD_ID quiere. Si prefieres no depender de ese endpoint, el cloud id también es el segmento después de /s/ en la URL de admin.atlassian.com → Apps → Sites → tu sitio.

2. Crea un token de API en id.atlassian.com.

3. Añade el servidor.

Claude Code:

claude mcp add jira-alerts-mcp \
  --scope user \
  --env JSM_CLOUD_ID='your-cloud-id' \
  --env JSM_EMAIL='you@example.com' \
  --env JSM_API_TOKEN="${JSM_API_TOKEN}" \
  --env JSM_TOOLSETS='all' \
  -- npx -y jira-alerts-mcp

JSM_TOOLSETS=all registra cada conjunto de herramientas verificado — 82 herramientas en lugar de las 28 que el valor predeterminado responder te da, añadiendo horarios, equipos, ventanas de mantenimiento y enrutamiento. Elimina la línea para empezar de forma reducida; all no es la superficie más amplia posible, porque las tres familias en cuarentena aún deben solicitarse por nombre. Consulta Elegir tus conjuntos de herramientas para ver qué cubre cada uno y por qué una lista de herramientas más grande no es automáticamente mejor.

--scope user registra el servidor para toda tu cuenta en lugar de solo el directorio donde ejecutaste el comando. Eso es lo que quieres para un servidor de alertas — lo quieres en cada sesión. Sin la bandera, claude mcp add por defecto tiene alcance local, y el servidor existe solo en ese directorio.

Claude Desktop: abre la configuración desde la aplicación en lugar de hacerlo a mano — el menú Claude en tu barra de menús (no la configuración dentro de la ventana) → Configuración → Desarrollador → Editar configuración. Eso crea el archivo si aún no existe:

{
  "mcpServers": {
    "jira-alerts-mcp": {
      "command": "npx",
      "args": ["-y", "jira-alerts-mcp"],
      "env": {
        "JSM_CLOUD_ID": "your-cloud-id",
        "JSM_EMAIL": "you@example.com",
        "JSM_API_TOKEN": "your-api-token",
        "JSM_TOOLSETS": "all"
      }
    }
  }
}

mcpServers es una clave de nivel superior, y el archivo contiene cada servidor que tienes configurado. Si ya tiene un bloque mcpServers, añade jira-alerts-mcp como otra entrada dentro de él — pegar todo el bloque anterior sobre el archivo reemplaza lo que ya estaba allí.

Luego sal de Claude Desktop por completo y vuelve a abrirlo — el archivo se lee solo al inicio, y cerrar la ventana no es salir. El servidor aparece entonces bajo el panel de conectores en el compositor de mensajes.

La mayoría de los otros clientes MCP aceptan esa misma forma JSON. No hay elección de alcance que hacer aquí — claude_desktop_config.json ya es por usuario, el mismo alcance que --scope user en la CLI.

4. Verifica que funciona. Pide a tu agente que liste tus alertas abiertas. Eso ejecuta jsm_list_alerts, que no necesita ids y confirma tus credenciales y el alcance read:ops-alert que comparten nueve de las catorce herramientas.

Luego pregunta quién está de guardia, que ejecuta jsm_list_schedules. Esa es una verificación separada, porque los horarios necesitan read:ops-config — si las alertas funcionan y los horarios devuelven 401, no hay nada malo con tu token; consulta Alcances requeridos abajo.

Cosas que sorprenden a la gente: con claude mcp add el nombre del servidor es el primer argumento posicional, antes de cualquier bandera; -y en npx omite el aviso de instalación, que un cliente MCP no tiene forma de responder; y en zsh ${VAR} necesita comillas. Un servidor añadido sin --scope user funciona en el directorio desde donde lo añadiste y simplemente falta en todos los demás lugares, sin error que explique la ausencia — si parece haber desaparecido, ejecuta claude mcp list desde un directorio diferente antes de tocar cualquier otra cosa. Para sesiones iniciadas por GUI, el token debe vivir en el bloque env de la configuración misma — el entorno del shell no se hereda, que es por lo que el JSON anterior lleva las credenciales en línea.

Si el servidor nunca aparece en Claude Desktop, dos causas explican casi todos los casos, y ninguna se anuncia a sí misma:

• npx no estaba en el PATH. Una aplicación GUI se inicia por el gestor de ventanas, no por un shell, por lo que un Node instalado a través de nvm a menudo no es visible para ella. Establece "command" a la ruta absoluta de which node y apunta "args" al dist/index.js instalado, o instala Node a nivel de sistema. Un Node anterior a 24 que sí se encuentra falla como EBADENGINE en lugar de algo legible.
• El servidor salió durante el inicio. Las credenciales se validan antes del protocolo de enlace, por lo que un cloud id o token incorrecto lo detiene por completo — y como stdout es el canal de protocolo, ese mensaje va solo a stderr. Claude Desktop lo mantiene en ~/Library/Logs/Claude/mcp-server-jira-alerts-mcp.log (Windows: %APPDATA%\Claude\logs\), nombrado según la clave que usaste bajo mcpServers. Busca Startup failed: — nombra exactamente lo que está mal.

git clone https://github.com/rrvrs/jira-alerts-mcp.git
cd jira-alerts-mcp
npm install
npm run build

  -- node /absolute/path/to/jira-alerts-mcp/dist/index.js

Configuración

Las credenciales se validan al inicio, por lo que una configuración incorrecta falla inmediatamente con un mensaje accionable en lugar de en la primera llamada de herramienta.

.env.example los lista como referencia. El servidor no lee .env por sí mismo — un servidor MCP es lanzado por su cliente, y el cliente posee el entorno. Usa el archivo como lista de verificación para el bloque env de tu cliente, o set -a; source .env; set +a para desarrollo local.

Qué pueden y qué no pueden hacer tus credenciales

Ambos métodos de autenticación no son equivalentes, y la diferencia no está documentada por Atlassian. Verificado contra un tenant en vivo el 2026-09-05:

Los alcances de eliminación se otorgan por token, no por método de autenticación. Dos tokens de API de cuenta Atlassian para la misma cuenta se comportan de manera diferente: uno fue rechazado en cada DELETE con 401 Unauthorized; scope does not match — credenciales válidas, concesión faltante — y otro completó todo el conjunto. Así que un 401 en una eliminación no es una razón para abandonar JSM_EMAIL + JSM_API_TOKEN. Reemite el token con los alcances de eliminación incluidos, o proporciona un token OAuth 3LO o Forge otorgado delete:ops-alert:jira-service-management como JSM_OAUTH_TOKEN. El manejador de 401 dice exactamente esto, por lo que el modelo lo informa en lugar de reintentar.

Las herramientas de alerta respaldadas por eliminación son jsm_delete_alert · jsm_delete_alert_note · jsm_remove_alert_tags · jsm_remove_alert_extra_properties · jsm_delete_alert_attachment.

Los endpoints de adjuntos de alerta están bloqueados dos veces. El documento OpenAPI de la API los mapea a ningún alcance OAuth en absoluto, por lo que un token que carece de los alcances de eliminación es rechazado en la puerta de enlace con el mismo scope does not match desnudo — que parece un callejón sin salida de autenticación y no lo es. Un token con todos los alcances llega a la API y recibe Feature not available in your plan en su lugar. En un sitio cuyo plan excluye adjuntos, ningún token los abre, que es por lo que ahora viven en su propio conjunto de herramientas attachments en cuarentena que ningún perfil carga. El manejador informa el límite del plan como un límite del plan en lugar de enviarte a ampliar un token.

Algunas acciones dependen de tu plan JSM, no de tus alcances. En un tenant Standard, las acciones de posponer, asignar y personalizadas se aceptan y luego fallan fuera de banda con Your account plan does not support …. La solicitud está bien formada; el plan es el límite. Esto es exactamente por qué las escrituras son asíncronas y por qué jsm_get_request_status importa — la respuesta inmediata a las tres es un recibo exitoso.

Qué se ha y qué no se ha verificado

Cada herramienta en este servidor se ejecutó contra un sitio Jira Service Management en vivo antes del lanzamiento. Cada herramienta que un perfil puede cargar devolvió un éxito real — eso es un invariante, y una prueba lo hace cumplir: un conjunto de herramientas marcado como no verificado no puede aparecer en un perfil.

Tres familias no pudieron verificarse, y se envían en cuarentena en lugar de eliminadas. Nada sobre ellas se sabe que esté roto; no fueron probables en el sitio disponible, y el código es muy probablemente correcto para un sitio donde no están bloqueadas.

Habilita una nombrándola junto con lo que más quieras:

"env": { "JSM_TOOLSETS": "all,heartbeats" }

jsm_list_capabilities informa lo mismo en tiempo de ejecución, por lo que un asistente que pregunta "¿puedes crear un heartbeat?" recibe la respuesta de que la familia existe, está apagada, cómo activarla, y que nunca se vio funcionar — en lugar de adivinar. Dos familias se eliminaron en 2.0.0 en lugar de ponerse en cuarentena. Las políticas de alertas (11 herramientas) y los roles de usuario personalizados (6 herramientas) respondieron a 403 You are not authorized bajo dos credenciales separadas, una de ellas con Jira ADMINISTER. Los roles de usuario personalizados son una función Enterprise de Opsgenie, y el rechazo de la política parece el mismo tipo de límite. Enviar diecisiete herramientas cuya única evidencia era que compilaban no valía el peso en la lista de herramientas, así que se eliminaron. Si tienes un sitio donde funcionan y quieres recuperarlas, abre un issue — el código está en el historial y el guardián de deriva aún conoce los endpoints.

Elegir tus conjuntos de herramientas

La API de operaciones de JSM tiene aproximadamente 240 operaciones. Registrar todas entregaría a tu cliente una lista de herramientas que no puede elegir con precisión, así que la superficie se divide en conjuntos de herramientas con nombre y tú eliges:

Tres más se envían pero ningún perfil las carga — consulta Qué se ha verificado y qué no:

Además, cuatro perfiles, que son paquetes de lo anterior:

"env": { "JSM_TOOLSETS": "responder" }     // or "alerts,oncall", or "all"

Los nombres se combinan libremente, y las banderas --toolsets=a,b y --read-only anulan el entorno. Un nombre que no esté en las tablas anteriores detiene el servidor al inicio con los nombres válidos y una sugerencia — un error tipográfico no debería dejarte silenciosamente con menos herramientas de las que pediste.

core es una lista congelada de nombres — la superficie que este servidor tenía antes de que existieran los conjuntos — mantenida para que una instalación que quiera exactamente eso pueda pedirla sin listar trece herramientas. Mantiene esas catorce al combinarse: core,schedules es core más cada herramienta de horarios, no ambas familias sin restricciones, así que añadir un conjunto a su lado no puede ampliar lo que core mismo contribuye. responder se deriva de sus conjuntos y se amplía a medida que llegan familias, por eso es el predeterminado: un servidor de alertas cuyas herramientas de alerta son en su mayoría invisibles hasta que lo reconfiguras no sirve de mucho.

all significa cada conjunto verificado, no cada conjunto. Las tres familias en cuarentena deben nombrarse por sí solas — JSM_TOOLSETS=all,heartbeats — para que pedir todo no pueda entregarte herramientas que nunca se han visto funcionar.

jsm_list_capabilities siempre se registra, sin importar lo que selecciones. Informa cada conjunto, si está cargado, sus alcances y la variable a cambiar — así que cuando pides algo que la selección actual no cubre, obtienes "eso está en el conjunto oncall" en lugar de "este servidor no puede hacer eso". Cambiar JSM_TOOLSETS requiere un reinicio; nada puede habilitar un conjunto a mitad de conversación.

Alcances requeridos. Las alertas y la guardia están detrás de alcances diferentes, que es el error de configuración más común:

Tres consecuencias que vale la pena conocer antes de acuñar un token:

• Las escrituras también necesitan el alcance de lectura. Un token que solo lleva write:ops-alert:jira-service-management falla. Atlassian requiere el alcance de lectura junto a él en cada endpoint de escritura.

• ops-config es una concesión separada, y una falta devuelve 401, no 403. Omítelo y las nueve herramientas de alertas funcionan perfectamente mientras las cuatro de guardia fallan — lo que parece una credencial rota y no lo es. Ambas son configuraciones compatibles: otorgar solo los alcances de lectura, o solo ops-alert, es una forma deliberada de reducir lo que el agente puede alcanzar.

• El alcance de usuario de Jira es opcional, y su ausencia es visible en lugar de silenciosa. Cada respondedor que devuelve la API de operaciones es un id de cuenta desnudo (712020:9ae5385e-…); con read:jira-user las herramientas de guardia resuelven esos a nombres y correos en la misma llamada. Sin él, aún responden — obtienes los ids, más una línea que dice qué alcance los habría nombrado. Saber quién está de guardia importa más que saber su nombre visible, así que un alcance faltante aquí nunca se convierte en un error.

  Usa read:jira-user, no read:user:jira. El esquema granular sí cubre estos endpoints, pero solo como el conjunto completo read:application-role:jira + read:group:jira + read:user:jira + read:avatar:jira — read:user:jira por sí solo no es suficiente, y Atlassian aún marca todo el conjunto granular como Beta para esta API.

Visibilidad de equipo. La cuenta también necesita acceso a operaciones de JSM en el equipo relevante. Las alertas y horarios cuelgan de la página de operaciones de un equipo, así que las credenciales que no pueden ver el equipo obtendrán listas vacías en lugar de errores.

Ejemplo

Preguntar quién está de guardia se resuelve a jsm_list_schedules, luego jsm_get_on_call:

tú — ¿quién está de guardia para pagos ahora mismo?

# Currently on-call for Payments — Primary

- Dana Okafor

Reconocer una alerta devuelve un recibo, no la alerta actualizada — porque JSM aplica las acciones de alerta fuera de banda:

tú — reconoce la alerta 4f2a9c1e-…-1718395200000, la estoy mirando

Acknowledge request accepted for alert `4f2a9c1e-…-1718395200000`.

- **Request id**: `c7b41f30-…`
- **Result**: Request will be processed

JSM applies alert actions asynchronously, so the alert may not reflect this
change immediately. Confirm with jsm_get_request_status using the request id
above, or re-read the alert after a moment.

Ese último párrafo es el punto: sin él, un agente vuelve a leer la alerta, la ve aún sin reconocer y la reconoce de nuevo.

Herramientas

Noventa y cinco herramientas en diez conjuntos: alerts, alert-actions, oncall, schedules, teams, maintenance, routing, heartbeats, attachments y forwarding. Las primeras tres se registran por defecto; el resto se cargan solo cuando JSM_TOOLSETS las nombra, y jsm_list_capabilities informa en tiempo de ejecución cuáles de ellas tiene realmente esta instalación.

TOOLS.md es el catálogo: cada herramienta con el endpoint detrás de ella, si lee o escribe, cuáles están marcadas como destructivas y las advertencias que vienen con cada familia.

Reduce la superficie con JSM_TOOLSETS o JSM_READ_ONLY — consulta Elegir tus conjuntos de herramientas.

Qué maneja este servidor por ti

Tres comportamientos de la API rompen silenciosamente integraciones ingenuas. Cada uno se indica en las descripciones de herramientas, donde el modelo realmente lo leerá:

1. Las escrituras son asíncronas. Cada endpoint de mutación devuelve { result, requestId, took } inmediatamente y aplica el cambio fuera de banda. Volver a leer la alerta justo después de un reconocimiento a menudo la mostrará aún sin reconocer. jsm_get_request_status es la ruta de verificación correcta, y cada herramienta de escritura apunta a ella.

2. tinyId no es un id. El número corto en la interfaz de JSM (#4821) es rechazado por /v1/alerts/{id}, que acepta solo el id completo uuid-timestamp. Los alias necesitan un endpoint completamente diferente (/v1/alerts/alias?alias=). Tanto las descripciones de esquema como el manejador de 404 lo dicen explícitamente, así que el modelo se autocorrige en lugar de reintentar la misma llamada.

3. La ventana de búsqueda tiene un tope de 20,000. offset + limit debe mantenerse por debajo. jsm_list_alerts rechaza la paginación más profunda localmente con un mensaje que le dice al modelo que estreche la consulta en lugar de gastar un viaje de ida y vuelta en un 400 garantizado.

4. Las acciones de alerta no aceptan actor ni nota. Opsgenie aceptaba user, source y note junto con un reconocimiento o un cierre, y JSM Operations es un rehospedaje de Opsgenie — pero no declara cuerpo de solicitud para esos endpoints y descarta los campos silenciosamente. Reconocer con una nota y leer el registro de actividad de vuelta no muestra ni la nota ni el actor. Así que estas herramientas no ofrecen los parámetros en absoluto: un argumento rechazado es un hecho sobre el que el modelo puede actuar, mientras que uno ignorado parece una decisión registrada que en realidad ha desaparecido. Para dejar una nota duradera, llama a jsm_add_alert_note. jsm_create_alert sí acepta note y source, porque CreateAlertRequest declara ambos y la API los honra — también verificado.

Por qué existe esto

Las alertas no son elementos de trabajo. Viven detrás de una API diferente — /jsm/ops/api, la superficie rehospedada de Opsgenie — con sus propios alcances, su propio formato de id y su propia semántica de escritura asíncrona. El registro de MCP lista 30 servidores de Jira; cada uno de ellos habla con elementos de trabajo. Ninguno puede decirte qué te está paginando ahora mismo. atlassian/atlassian-mcp-server reduce la brecha pero no la cierra. Desde febrero de 2026 envía cuatro herramientas de operaciones de JSM — getJsmOpsAlerts, getJsmOpsScheduleInfo, getJsmOpsTeamInfo y updateJsmOpsAlert — y son gruesas: un solo updateJsmOpsAlert cubre reconocer, desreconocer, cerrar y escalar, y nada cubre notas, registros, etiquetas, adjuntos, posponer, asignar, estado de solicitud, cronogramas, rotaciones, anulaciones, latidos, mantenimiento, enrutamiento, integraciones o registros de auditoría. También están ausentes del README de ese repositorio, documentadas solo en la página de herramientas compatibles de Atlassian, y eran solo de token de API al lanzamiento — una instalación de OAuth no ve ninguna. Al ser un servidor alojado y cerrado, esas brechas son de Atlassian para cerrar en lugar de algo que una contribución pueda arreglar.

Los servidores MCP de Opsgenie que existen hablan una API con fecha de caducidad. giantswarm/mcp-opsgenie, burakdirin/opsgenie-mcp-server y daviddykeuk/opsgenie-mcp todos llaman a api.opsgenie.com con una GenieKey. Opsgenie alcanzó el fin de venta el 4 de junio de 2025 y se apaga el 5 de abril de 2027, momento en el que esas APIs REST dejan de responder. Este servidor apunta a la superficie que las reemplaza: https://api.atlassian.com/jsm/ops/api/{cloudId}/v1.

Compatibilidad. Para inquilinos de Atlassian Cloud con operaciones de JSM — sitios ya migrados fuera de Opsgenie independiente, o aprovisionados después de la fusión. Si tu equipo aún inicia sesión en app.opsgenie.com y se autentica con una GenieKey, este servidor no alcanzará tus datos; uno de los servidores de Opsgenie anteriores sí lo hará, hasta 2027.

Estructura del proyecto

src/
├── index.ts                 # transports and startup credential validation
├── server.ts                # assembles the catalogue from the eight families
├── toolsets.ts              # toolsets, profiles, and selection resolution
├── constants.ts             # API root, limits
├── types.ts                 # JSM API interfaces
├── schemas/common.ts        # Zod fragments shared across families
├── services/
│   ├── client.ts            # auth, request, envelope normalisation, error mapping
│   ├── directory.ts         # resolves bare Atlassian ids to names
│   ├── name-cache.ts        # one registry for every process-wide cache
│   ├── format.ts            # markdown rendering, truncation, result envelopes
│   └── render/              # per-family renderers
└── tools/
    ├── define.ts            # defineTool() + registerTools()
    ├── family.ts            # the resource-family factory
    ├── execute-write.ts     # the shared write executor
    ├── list-executor.ts     # the shared list pipeline
    ├── paging.ts            # the paging dialects each endpoint wants
    ├── capabilities.ts      # jsm_list_capabilities
    ├── test-support.ts      # stub client and in-memory MCP harness
    ├── alerts/              # alert reads
    ├── actions/             # alert writes
    ├── oncall/              # who is on call now and next
    ├── schedules/           # schedules, rotations, overrides
    ├── teams/               # teams, roles, contact methods
    ├── maintenance/         # maintenance windows
    ├── heartbeats/          # heartbeat monitors
    └── routing/             # escalations, routing, notification, forwarding rules

Las familias de alertas están escritas con una herramienta por archivo: un módulo es dueño de su forma de entrada, su descripción y su manejador, y nada más. Las familias de configuración, en cambio, se generan — family.ts construye las formas mecánicas de listar/obtener/crear/actualizar/eliminar a partir de un ResourceConfig, porque escribir diez de ellas a mano serían cien archivos cuyas diferencias son de tres líneas cada uno. Cuando un endpoint no encaja en esas cinco formas, una herramienta escrita a mano se coloca junto a las generadas; teams/contacts.ts tiene ambas.

server.ts concatena las ocho familias en allTools, el catálogo completo. toolsets.ts lo reduce a lo que un proceso realmente registra, y index.ts solo conoce los transportes. El catálogo de herramientas en sí — cada herramienta, agrupada por familia — está en TOOLS.md.

Tres convenciones aquí son fundamentales, y cambiarlas por accidente es la forma más probable de romper el servidor de manera sutil. Están documentadas, con los errores que motivaron cada una, en Convenciones que vale la pena preservar.

Contribuciones

Consulta CONTRIBUTING.md para el ciclo de desarrollo, las convenciones que vale la pena preservar y cómo agregar una herramienta. Los problemas y las solicitudes de extracción no deben contener identificadores de nube, tokens ni datos reales de alertas.

Seguridad

Este servidor contiene credenciales de Atlassian, y el transporte HTTP no realiza autenticación propia — consulta SECURITY.md para el modelo de amenazas, notas de endurecimiento y cómo reportar una vulnerabilidad de forma privada.

Licencia

Apache-2.0