jira-alerts-mcp

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; reconócelas, ciérralas, anótalas 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 o 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 es también el segmento después de /s/ en la URL en 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}" \
  -- npx -y jira-alerts-mcp

--scope user registra el servidor para toda tu cuenta en lugar de solo el directorio desde el que 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 es el 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"
      }
    }
  }
}

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. Comprueba 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 comprobació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 el que 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 tiene que 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 todo, y ninguna se anuncia a sí misma:

• npx no estaba en el PATH. Una aplicación GUI es lanzada por el gestor de ventanas, no un shell, así que un Node instalado a través de nvm a menudo no es visible para ella. Establece "command" a la ruta absoluta desde 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 apretón de manos, así que un cloud id o token malo lo detiene en seco — y porque 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, así que una configuración mala falla inmediatamente con un mensaje accionable en lugar de en la primera llamada de herramienta.

.env.example las lista como referencia. El servidor no lee .env en sí — un servidor MCP es lanzado por su cliente, y el cliente es dueño del 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 un delete 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, así que el modelo lo reporta en lugar de reintentar.

Las herramientas de alerta respaldadas por delete 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 doblemente restringidos. El documento OpenAPI de la API los mapea a ningún alcance OAuth en absoluto, así 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 completamente con alcance llega a la API y se le dice 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 reporta 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 son aceptadas 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 ser verificadas, y se envían en cuarentena en lugar de eliminadas. Nada sobre ellas se sabe que esté roto; eran no probables en el sitio disponible, y el código es muy probablemente correcto para un sitio donde no están bloqueadas.

Habilita una nombrando junto a lo que sea que quieras:

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

jsm_list_capabilities reporta lo mismo en tiempo de ejecución, así que un asistente que pregunta "¿puedes crear un heartbeat?" se le dice que la familia existe, está apagada, cómo encenderla, y que nunca se vio funcionar — en lugar de adivinar.

Dos familias fueron eliminadas en 2.0.0 en lugar de puestas en cuarentena. Las políticas de alerta (11 herramientas) y los roles de usuario personalizados (6 herramientas) respondieron 403 You are not authorized bajo dos credenciales separadas, una de ellas con Jira ADMINISTER. Los roles de usuario personalizados son una característica 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 de la lista de herramientas, así que se fueron. Si tienes un sitio donde funcionan y quieres que vuelvan, 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 JSM Operations tiene aproximadamente 240 operaciones. Registrar todas ellas entregaría a tu cliente una lista de herramientas de la que no puede elegir con precisión, así que la superficie se divide en conjuntos de herramientas nombrados y tú eliges:

Tres más se incluyen, pero ningún perfil las carga: consulte 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 iniciar 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 de herramientas, mantenida para que una instalación que quiera exactamente eso pueda solicitarla sin enumerar trece herramientas. Conserva esas catorce al combinarse: core,schedules es core más cada herramienta de horarios, no ambas familias sin restricciones, por lo que agregar un conjunto de herramientas a su lado no puede ampliar lo que core contribuye por sí mismo. responder se deriva de sus conjuntos de herramientas 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 de herramientas verificado, no cada conjunto de herramientas. 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 ha visto que funcionen.

jsm_list_capabilities siempre está registrado, sin importar lo que selecciones. Informa cada conjunto de herramientas, si está cargado, sus alcances y la variable a cambiar, de modo que cuando pidas algo que la selección actual no cubre, obtengas "eso está en el conjunto de herramientas oncall" en lugar de "este servidor no puede hacer eso". Cambiar JSM_TOOLSETS requiere un reinicio; nada puede habilitar un conjunto de herramientas 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 faltante devuelve 401, no 403. Omítelo y las nueve herramientas de alertas funcionan perfectamente mientras las cuatro herramientas 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 limitar 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 Operations es un ID de cuenta simple (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 para mostrar, por lo que un alcance faltante aquí nunca se convierte en un error.

  Recurre a read:jira-user, no a 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 del equipo. La cuenta también necesita acceso a JSM Operations en el equipo relevante. Las alertas y los horarios dependen de la página de Operations de un equipo, por lo 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 en 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 revisando

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. Los primeros tres se registran por defecto; el resto se carga solo cuando JSM_TOOLSETS los nombra, y jsm_list_capabilities informa en tiempo de ejecución cuáles de ellos tiene realmente esta instalación.

TOOLS.md es el catálogo: cada herramienta con el endpoint detrás, 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: consulte Elegir tus conjuntos de herramientas.

Qué maneja este servidor por ti

Tres comportamientos de la API rompen silenciosamente las integraciones ingenuas. Cada uno se indica en las descripciones de las 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 del esquema como el manejador de 404 lo dicen explícitamente, por lo que el modelo se autocorrige en lugar de reintentar la misma llamada.

3. La ventana de búsqueda tiene un límite 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 reduzca 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. Por lo tanto, 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 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 incluye cuatro herramientas de JSM Operations — getJsmOpsAlerts, getJsmOpsScheduleInfo, getJsmOpsTeamInfo y updateJsmOpsAlert — y son gruesas: un solo updateJsmOpsAlert cubre reconocer, desreconocer, cerrar y escalar, y nada cubre notas, registros, etiquetas, archivos adjuntos, posponer, asignar, estado de solicitudes, 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 en el 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 sí existen hablan una API con fecha de vencimiento. giantswarm/mcp-opsgenie, burakdirin/opsgenie-mcp-server y daviddykeuk/opsgenie-mcp todos llaman a api.opsgenie.com con una GenieKey. Opsgenie llegó al fin de venta el 4 de junio de 2025 y se apaga el 5 de abril de 2027, momento en el que esas API 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 JSM Operations: sitios ya migrados desde 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 una herramienta por archivo: un módulo posee su forma de entrada, su descripción y su manejador, y nada más. Las familias de configuración se generan en su lugar: family.ts construye las formas mecánicas de listar/obtener/crear/actualizar/eliminar a partir de un ResourceConfig, porque escribir diez a mano serían cien archivos cuyas diferencias son tres líneas cada uno. Donde un endpoint no encaja en esas cinco formas, una herramienta escrita a mano se sienta 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 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 sutilmente. Están documentadas, con los errores que motivaron cada una, en Convenciones que vale la pena preservar.

Contribuciones

Consulta CONTRIBUTING.md para conocer el ciclo de desarrollo, las convenciones que vale la pena preservar y cómo agregar una herramienta. Los issues y PRs no deben contener IDs de nube, tokens ni datos reales de alertas.

Seguridad

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

Licencia

Apache-2.0