jira-alerts-mcp

Um servidor MCP para Jira Service Management Operations — a superfície de alertas que substituiu o Opsgenie, que nenhum outro servidor MCP do Jira cobre.

Pesquise alertas e leia suas notas e linha do tempo de atividades; reconheça, feche, anote e adicione respondedores; e consulte quem está de plantão agora e depois. Doze ferramentas, quatro delas de escrita.

Demonstração

Três perguntas em uma única sessão, contra um site JSM ao vivo: quem está de plantão, o que está aberto, e reconheça o que não está. Observe a última resposta em particular — o agente confirma que o reconhecimento realmente foi registrado (ack landed 16:38:00.577Z) em vez de assumir que foi, que é o comportamento de escrita assíncrona descrito em O que este servidor resolve para você.

Início rápido

Você precisa de Node ≥ 24 e um site Atlassian Cloud com JSM Operations habilitado. Não há nada para clonar ou compilar — seu cliente MCP executa o pacote publicado.

1. Encontre seu cloud id. Abra isto enquanto estiver logado no seu site:

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

Ele responde com uma linha — {"cloudId":"..."} — e esse UUID é o que JSM_CLOUD_ID quer. Se preferir não depender desse endpoint, o cloud id também é o segmento após /s/ na URL em admin.atlassian.com → Apps → Sites → seu site.

2. Crie um token de API em id.atlassian.com.

3. Adicione o 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 o servidor para toda a sua conta, em vez de apenas o diretório em que você executou o comando. É isso que você quer para um servidor de alertas — você o quer em todas as sessões. Sem a flag, claude mcp add padroniza para o escopo local, e o servidor existe apenas naquele diretório.

Claude Desktop: abra a configuração pelo aplicativo, não manualmente — o menu Claude na sua barra de menus (não as configurações dentro da janela) → Configurações → Desenvolvedor → Editar Configuração. Isso cria o arquivo se ele ainda não existir:

{
  "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 é uma chave de nível superior, e o arquivo contém todos os servidores que você configurou. Se ele já tiver um bloco mcpServers, adicione jira-alerts-mcp como outra entrada dentro dele — colar o bloco inteiro acima sobre o arquivo substitui o que já estava lá.

Depois, saia completamente do Claude Desktop e reabra-o — o arquivo é lido apenas na inicialização, e fechar a janela não é sair. O servidor então aparece sob o painel de conectores no compositor de mensagens.

A maioria dos outros clientes MCP aceita esse mesmo formato JSON. Não há escolha de escopo a fazer aqui — claude_desktop_config.json já é por usuário, o mesmo alcance que --scope user na CLI.

4. Verifique se funciona. Peça ao seu agente para listar seus alertas abertos. Isso executa jsm_list_alerts, que não precisa de ids e confirma suas credenciais e o escopo read:ops-alert que nove das quatorze ferramentas compartilham.

Depois pergunte quem está de plantão, o que executa jsm_list_schedules. Essa é uma verificação separada, porque os agendamentos precisam de read:ops-config — se os alertas funcionam e os agendamentos retornarem 401, não há nada errado com seu token; veja Escopos necessários abaixo.

Coisas que pegam as pessoas de surpresa: com claude mcp add, o nome do servidor é o primeiro argumento posicional, antes de qualquer flag; -y em npx pula o prompt de instalação, que um cliente MCP não tem como responder; e no zsh, ${VAR} precisa de aspas. Um servidor adicionado sem --scope user funciona no diretório de onde você o adicionou e simplesmente está ausente em todos os outros lugares, sem erro para explicar a ausência — se ele parecer ter desaparecido, execute claude mcp list de um diretório diferente antes de mexer em qualquer outra coisa. Para sessões iniciadas por GUI, o token precisa estar no bloco env da própria configuração — o ambiente do shell não é herdado, que é o motivo de o JSON acima carregar as credenciais inline.

Se o servidor nunca aparecer no Claude Desktop, duas causas explicam quase todos os casos, e nenhuma delas se anuncia:

• npx não estava no PATH. Um aplicativo GUI é iniciado pelo gerenciador de janelas, não por um shell, então um Node instalado via nvm muitas vezes não é visível para ele. Defina "command" para o caminho absoluto de which node e aponte "args" para o dist/index.js instalado, ou instale o Node em todo o sistema. Um Node mais antigo que 24 que é encontrado falha como EBADENGINE em vez de algo legível.
• O servidor saiu durante a inicialização. As credenciais são validadas antes do handshake, então um cloud id ou token inválido o interrompe — e como o stdout é o canal de protocolo, essa mensagem vai apenas para o stderr. O Claude Desktop o mantém em ~/Library/Logs/Claude/mcp-server-jira-alerts-mcp.log (Windows: %APPDATA%\Claude\logs\), nomeado pela chave que você usou sob mcpServers. Procure por Startup failed: — ele nomeia exatamente o que está errado.

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

Configuração

As credenciais são validadas na inicialização, então uma configuração inválida falha imediatamente com uma mensagem acionável em vez de na primeira chamada de ferramenta.

.env.example lista estas para referência. O servidor não lê .env por conta própria — um servidor MCP é iniciado pelo seu cliente, e o cliente é dono do ambiente. Use o arquivo como uma lista de verificação para o bloco env do seu cliente, ou set -a; source .env; set +a para desenvolvimento local.

O que suas credenciais podem e não podem fazer

Ambos os métodos de autenticação não são equivalentes, e a diferença não é documentada pela Atlassian. Verificado contra um tenant ativo em 2026-09-05:

Os escopos de exclusão são concedidos por token, não por método de autenticação. Dois tokens de API de conta Atlassian para a mesma conta se comportam de forma diferente: um foi recusado em todo DELETE com 401 Unauthorized; scope does not match — credenciais válidas, concessão ausente — e outro completou o conjunto inteiro. Então um 401 em uma exclusão não é motivo para abandonar JSM_EMAIL + JSM_API_TOKEN. Reemita o token com os escopos de exclusão incluídos, ou forneça um token OAuth 3LO ou Forge concedido delete:ops-alert:jira-service-management como JSM_OAUTH_TOKEN. O manipulador de 401 diz exatamente isso, então o modelo o relata em vez de tentar novamente.

As ferramentas de alerta baseadas em exclusão são jsm_delete_alert · jsm_delete_alert_note · jsm_remove_alert_tags · jsm_remove_alert_extra_properties · jsm_delete_alert_attachment.

Os endpoints de anexos de alerta são protegidos duas vezes. O documento OpenAPI da própria API os mapeia para nenhum escopo OAuth, então um token sem os escopos de exclusão é recusado no gateway com o mesmo scope does not match simples — que parece um beco sem saída de autenticação e não é. Um token totalmente escopado chega à API e recebe Feature not available in your plan em vez disso. Em um site cujo plano exclui anexos, nenhum token os abre, que é o motivo de eles agora viverem em seu próprio conjunto de ferramentas attachments em quarentena que nenhum perfil carrega. O manipulador relata o limite do plano como um limite do plano, em vez de enviar você para ampliar um token.

Algumas ações dependem do seu plano JSM, não dos seus escopos. Em um tenant Standard, adiar, atribuir e ações personalizadas são aceitas e depois falham fora de banda com Your account plan does not support …. A solicitação é bem formada; o plano é o limite. É exatamente por isso que as escritas são assíncronas e por que jsm_get_request_status importa — a resposta imediata para todas as três é um recibo bem-sucedido.

O que foi e o que não foi verificado

Cada ferramenta neste servidor foi executada contra um site Jira Service Management ativo antes do lançamento. Cada ferramenta que um perfil pode carregar retornou um sucesso real — isso é um invariante, e um teste o aplica: um conjunto de ferramentas marcado como não verificado não pode aparecer em um perfil.

Três famílias não puderam ser verificadas, e elas são enviadas em quarentena em vez de removidas. Nada sobre elas é conhecido por estar quebrado; elas eram impossíveis de testar no site disponível, e o código é muito provavelmente correto para um site onde elas não são bloqueadas.

Habilite um nomeando-o junto com o que mais você quiser:

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

jsm_list_capabilities relata a mesma coisa em tempo de execução, então um assistente perguntando "você pode criar um heartbeat?" é informado de que a família existe, está desligada, como ligá-la, e que nunca foi vista funcionando — em vez de adivinhar.

Duas famílias foram removidas na 2.0.0 em vez de colocadas em quarentena. Políticas de alerta (11 ferramentas) e funções de usuário personalizadas (6 ferramentas) responderam 403 You are not authorized sob duas credenciais separadas, uma delas com Jira ADMINISTER. Funções de usuário personalizadas é um recurso Enterprise do Opsgenie, e a recusa de política parece o mesmo tipo de limite. Enviar dezessete ferramentas cuja única evidência era que compilavam não valia o peso da lista de ferramentas, então elas se foram. Se você tem um site onde elas funcionam e quer de volta, abra uma issue — o código está no histórico e o guarda de deriva ainda conhece os endpoints.

Escolhendo seus conjuntos de ferramentas

A API JSM Operations tem aproximadamente 240 operações. Registrar todas elas entregaria ao seu cliente uma lista de ferramentas que ele não consegue escolher com precisão, então a superfície é dividida em conjuntos de ferramentas nomeados e você escolhe:

Mais três são fornecidos, mas nenhum perfil os carrega — veja O que foi e o que não foi verificado:

Além de quatro perfis, que são pacotes dos itens acima:

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

Os nomes se combinam livremente, e os sinalizadores --toolsets=a,b e --read-only substituem o ambiente. Um nome que não esteja nas tabelas acima interrompe o servidor na inicialização com os nomes válidos e uma sugestão — um erro de digitação não deve deixar você silenciosamente com menos ferramentas do que pediu.

core é uma lista congelada de nomes — a superfície que este servidor tinha antes dos conjuntos de ferramentas existirem — mantida para que uma instalação que queira exatamente isso possa solicitá-la sem listar treze ferramentas. Ela mantém esses quatorze quando combinada: core,schedules é core mais todas as ferramentas de agenda, não ambas as famílias sem restrição, então adicionar um conjunto de ferramentas ao lado dela não pode ampliar o que core contribui. responder é derivado de seus conjuntos de ferramentas e se amplia à medida que as famílias chegam, por isso é o padrão: um servidor de alertas cujas ferramentas de alerta são em sua maioria invisíveis até você reconfigurá-lo não é muito útil.

all significa todos os conjuntos de ferramentas verificados, não todos os conjuntos de ferramentas. As três famílias em quarentena precisam ser nomeadas por conta própria — JSM_TOOLSETS=all,heartbeats — para que pedir tudo não possa entregar ferramentas que nunca foram vistas funcionando.

jsm_list_capabilities é sempre registrado, independentemente do que você selecionar. Ele relata cada conjunto de ferramentas, se está carregado, seus escopos e a variável a ser alterada — então quando você pede algo que a seleção atual não cobre, você recebe "isso está no conjunto de ferramentas oncall" em vez de "este servidor não pode fazer isso". Alterar JSM_TOOLSETS exige reinicialização; nada pode habilitar um conjunto de ferramentas no meio da conversa.

Escopos obrigatórios. Alertas e plantão estão atrás de escopos diferentes, que é o erro de configuração mais comum:

Três consequências que valem a pena saber antes de cunhar um token:

• Gravações também precisam do escopo de leitura. Um token contendo apenas write:ops-alert:jira-service-management falha. A Atlassian exige o escopo de leitura junto com ele em todo endpoint de gravação.

• ops-config é uma concessão separada, e uma ausência retorna 401, não 403. Omita-o e as nove ferramentas de alerta funcionam perfeitamente enquanto as quatro ferramentas de plantão falham — o que parece uma credencial quebrada e não é. Ambas são configurações suportadas: conceder apenas os escopos de leitura, ou apenas ops-alert, é uma forma deliberada de restringir o que o agente pode alcançar.

• O escopo do usuário Jira é opcional, e sua ausência é visível em vez de silenciosa. Cada respondente que a API de Operações retorna é um ID de conta simples (712020:9ae5385e-…); com read:jira-user as ferramentas de plantão resolvem esses para nomes e e-mails na mesma chamada. Sem ele, elas ainda respondem — você recebe os IDs, mais uma linha dizendo qual escopo os nomearia. Saber quem está de plantão importa mais do que saber o nome de exibição, então um escopo ausente aqui nunca se transforma em erro.

  Use read:jira-user, não read:user:jira. O esquema granular cobre esses endpoints, mas apenas como o conjunto completo read:application-role:jira + read:group:jira + read:user:jira + read:avatar:jira — read:user:jira sozinho não é suficiente, e a Atlassian ainda marca todo o conjunto granular como Beta para esta API.

Visibilidade da equipe. A conta também precisa de acesso às Operações JSM na equipe relevante. Alertas e agendas dependem da página de Operações de uma equipe, então credenciais que não conseguem ver a equipe receberão listas vazias em vez de erros.

Exemplo

Perguntar quem está de plantão resolve para jsm_list_schedules, depois jsm_get_on_call:

você — quem está de plantão para pagamentos agora?

# Currently on-call for Payments — Primary

- Dana Okafor

Reconhecer um alerta retorna um recibo, não o alerta atualizado — porque o JSM aplica ações de alerta fora de banda:

você — reconhecer alerta 4f2a9c1e-…-1718395200000, estou analisando

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.

Esse último parágrafo é o ponto: sem ele, um agente relê o alerta, vê que ele ainda não foi reconhecido e o reconhece novamente.

Ferramentas

Noventa e cinco ferramentas em dez conjuntos de ferramentas: alerts, alert-actions, oncall, schedules, teams, maintenance, routing, heartbeats, attachments e forwarding. Os três primeiros são registrados por padrão; o restante carrega apenas quando JSM_TOOLSETS os nomeia, e jsm_list_capabilities relata em tempo de execução quais deles esta instalação realmente possui.

TOOLS.md é o catálogo: cada ferramenta com o endpoint por trás dela, se lê ou grava, quais são marcadas como destrutivas e as ressalvas que vêm com cada família.

Reduza a superfície com JSM_TOOLSETS ou JSM_READ_ONLY — veja Escolhendo seus conjuntos de ferramentas.

O que este servidor trata por você

Três comportamentos da API quebram silenciosamente integrações ingênuas. Cada um é declarado nas descrições das ferramentas, onde o modelo realmente o lerá:

1. Gravações são assíncronas. Todo endpoint de mutação retorna { result, requestId, took } imediatamente e aplica a alteração fora de banda. Reler o alerta logo após um reconhecimento geralmente mostrará que ele ainda não foi reconhecido. jsm_get_request_status é o caminho de verificação correto, e cada ferramenta de gravação aponta para ele.

2. tinyId não é um ID. O número curto na interface do JSM (#4821) é rejeitado por /v1/alerts/{id}, que aceita apenas o ID completo uuid-timestamp. Aliases precisam de um endpoint completamente diferente (/v1/alerts/alias?alias=). Tanto as descrições de esquema quanto o manipulador de 404 dizem isso explicitamente, então o modelo se autocorrige em vez de tentar a mesma chamada novamente.

3. A janela de busca tem limite de 20.000. offset + limit deve permanecer abaixo disso. jsm_list_alerts rejeita paginação mais profunda localmente com uma mensagem dizendo ao modelo para restringir a consulta em vez de gastar uma ida e volta em um 400 garantido.

4. Ações de alerta não aceitam ator ou nota. Opsgenie aceitava user, source e note junto com um reconhecimento ou fechamento, e o JSM Operations é um re-hospedado do Opsgenie — mas ele não declara corpo de solicitação para esses endpoints e descarta os campos silenciosamente. Reconhecer com uma nota e ler o log de atividade de volta não mostra nem a nota nem o ator. Então essas ferramentas não oferecem os parâmetros: um argumento rejeitado é um fato sobre o qual o modelo pode agir, enquanto um ignorado parece uma decisão registrada que na verdade desapareceu. Para deixar uma nota durável, chame jsm_add_alert_note. jsm_create_alert aceita note e source, porque CreateAlertRequest declara ambos e a API os honra — também verificado.

Por que isso existe

Alertas não são itens de trabalho. Eles vivem atrás de uma API diferente — /jsm/ops/api, a superfície re-hospedada do Opsgenie — com seus próprios escopos, seu próprio formato de ID e sua própria semântica de gravação assíncrona. O Registro MCP lista 30 servidores Jira; cada um deles fala com itens de trabalho. Nenhum pode dizer o que está paginando você agora. atlassian/atlassian-mcp-server reduz a lacuna, mas não a fecha. Desde fevereiro de 2026, ele fornece quatro ferramentas de Operações JSM — getJsmOpsAlerts, getJsmOpsScheduleInfo, getJsmOpsTeamInfo e updateJsmOpsAlert — e elas são grosseiras: um único updateJsmOpsAlert cobre reconhecer, desreconhecer, fechar e escalar, e nada cobre notas, logs, tags, anexos, adiar, atribuir, status de solicitação, cronogramas, rotações, sobreposições, heartbeats, manutenção, roteamento, integrações ou logs de auditoria. Elas também estão ausentes do README desse repositório, documentadas apenas na página de ferramentas suportadas da Atlassian, e eram somente com token de API no lançamento — uma instalação OAuth não vê nenhuma delas. Sendo um servidor hospedado e fechado, essas lacunas são da Atlassian para fechar, em vez de algo que uma contribuição possa corrigir.

Os servidores MCP do Opsgenie que existem falam uma API com data de término. giantswarm/mcp-opsgenie, burakdirin/opsgenie-mcp-server e daviddykeuk/opsgenie-mcp todos chamam api.opsgenie.com com uma GenieKey. Opsgenie atingiu o fim das vendas em 4 de junho de 2025 e será desligado em 5 de abril de 2027, momento em que essas APIs REST param de responder. Este servidor tem como alvo a superfície que as substitui: https://api.atlassian.com/jsm/ops/api/{cloudId}/v1.

Compatibilidade. Para locatários Atlassian Cloud com JSM Operations — sites já migrados do Opsgenie independente, ou provisionados após a fusão. Se sua equipe ainda faz login em app.opsgenie.com e autentica com uma GenieKey, este servidor não alcançará seus dados; um dos servidores Opsgenie acima alcançará, até 2027.

Estrutura do projeto

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

As famílias de alertas são escritas uma ferramenta por arquivo: um módulo possui sua forma de entrada, sua descrição e seu manipulador, e nada mais. As famílias de configuração são geradas em vez disso — family.ts constrói as formas mecânicas listar/obter/criar/atualizar/excluir a partir de um ResourceConfig, porque escrever dez delas manualmente seria cem arquivos cujas diferenças são três linhas cada. Onde um endpoint não se encaixa nessas cinco formas, uma ferramenta escrita à mão fica ao lado das geradas; teams/contacts.ts tem ambas.

server.ts concatena as oito famílias em allTools, o catálogo completo. toolsets.ts reduz isso ao que um processo realmente registra, e index.ts só conhece transportes. O catálogo de ferramentas em si — cada ferramenta, agrupada por família — está em TOOLS.md.

Três convenções aqui são estruturais, e alterá-las por acidente é a maneira mais provável de quebrar o servidor sutilmente. Elas estão documentadas, com os bugs que motivaram cada uma, em Convenções que valem a pena preservar.

Contribuindo

Consulte CONTRIBUTING.md para o ciclo de desenvolvimento, as convenções que valem a pena preservar e como adicionar uma ferramenta. Issues e PRs não devem conter IDs de nuvem, tokens ou dados reais de alertas.

Segurança

Este servidor armazena credenciais do Atlassian, e o transporte HTTP não realiza autenticação própria — veja SECURITY.md para o modelo de ameaças, notas de endurecimento e como relatar uma vulnerabilidade de forma privada.

Licença

Apache-2.0