Atlassian Jira

Integra IA com o Atlassian Jira para gerenciar projetos, pesquisar issues e visualizar informações de desenvolvimento, como commits e pull requests.

GitHub
72

Documentação

Conecte a IA aos Seus Projetos Jira

Transforme como você gerencia e acompanha seu trabalho conectando Claude, Cursor AI e outros assistentes de IA diretamente aos seus projetos, issues e workflows do Jira. Obtenha insights instantâneos sobre projetos, simplifique o gerenciamento de issues e melhore a colaboração da sua equipe.

NPM Version

O Que Você Pode Fazer

  • Pergunte à IA sobre seus projetos: "Quais são as issues ativas no projeto DEV?"
  • Obtenha insights sobre issues: "Mostre-me detalhes sobre PROJ-123 incluindo comentários"
  • Acompanhe o progresso do projeto: "Liste todas as issues de alta prioridade atribuídas a mim"
  • Gerencie comentários de issues: "Adicione um comentário à PROJ-456 sobre os resultados dos testes"
  • Pesquise entre projetos: "Encontre todos os bugs em andamento nos meus projetos"
  • Crie e atualize issues: "Crie um novo bug no projeto MOBILE"

Perfeito Para

  • Desenvolvedores que precisam de acesso rápido aos detalhes de issues e contexto de desenvolvimento
  • Gerentes de Projeto acompanhando progresso, prioridades e atribuições de equipe
  • Scrum Masters gerenciando sprints e estados de workflow
  • Líderes de Equipe monitorando a saúde do projeto e a resolução de issues
  • Engenheiros de QA rastreando bugs e status de testes
  • Qualquer pessoa que queira interagir com o Jira usando linguagem natural

Início Rápido

Comece a usar em 2 minutos:

1. Obtenha Suas Credenciais do Jira

Gere um Token de API do Jira:

  1. Acesse Atlassian API Tokens
  2. Clique em Create API token
  3. Dê um nome como "AI Assistant"
  4. Copie o token gerado imediatamente (você não o verá novamente!)

2. Experimente Imediatamente

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Jira projects
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# Get details about a specific project
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/DEV"

# Get an issue with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/issue/PROJ-123" --jq "{key: key, summary: fields.summary, status: fields.status.name}"

Conecte-se aos Assistentes de IA

Para Usuários do Claude Desktop

Adicione isto ao seu arquivo de configuração do Claude (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Reinicie o Claude Desktop e você verá o servidor jira na barra de status.

Para Outros Assistentes de IA

A maioria dos assistentes de IA suporta MCP. Instale o servidor globalmente:

npm install -g @aashari/mcp-server-atlassian-jira

Em seguida, configure seu assistente de IA para usar o servidor MCP com transporte STDIO.

Alternativa: Arquivo de Configuração

Crie ~/.mcp/configs.json para configuração em todo o sistema:

{
  "jira": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

Chaves de configuração alternativas: O sistema também aceita "atlassian-jira", "@aashari/mcp-server-atlassian-jira" ou "mcp-server-atlassian-jira" em vez de "jira".

Ferramentas Disponíveis

Este servidor MCP fornece 5 ferramentas genéricas que podem acessar qualquer endpoint da API do Jira:

FerramentaDescrição
jira_getGET em qualquer endpoint da API do Jira (ler dados)
jira_postPOST em qualquer endpoint (criar recursos)
jira_putPUT em qualquer endpoint (substituir recursos)
jira_patchPATCH em qualquer endpoint (atualizações parciais)
jira_deleteDELETE em qualquer endpoint (remover recursos)

Caminhos de API Comuns

Projetos:

  • /rest/api/3/project/search - Listar todos os projetos (paginado, recomendado)
  • /rest/api/3/project - Listar todos os projetos (não paginado, legado)
  • /rest/api/3/project/{projectKeyOrId} - Obter detalhes do projeto

Issues:

  • /rest/api/3/search/jql - Pesquisar issues com JQL (use o parâmetro de consulta jql). IMPORTANTE: /rest/api/3/search está obsoleto!
  • /rest/api/3/issue/{issueIdOrKey} - Obter detalhes da issue
  • /rest/api/3/issue - Criar issue (POST)
  • /rest/api/3/issue/{issueIdOrKey}/transitions - Obter/executar transições

Comentários:

  • /rest/api/3/issue/{issueIdOrKey}/comment - Listar/adicionar comentários
  • /rest/api/3/issue/{issueIdOrKey}/comment/{commentId} - Obter/atualizar/excluir comentário

Worklogs:

  • /rest/api/3/issue/{issueIdOrKey}/worklog - Listar/adicionar worklogs
  • /rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId} - Obter/atualizar/excluir worklog

Usuários e Status:

  • /rest/api/3/myself - Obter usuário atual
  • /rest/api/3/user/search - Pesquisar usuários (use o parâmetro query)
  • /rest/api/3/status - Listar todos os status
  • /rest/api/3/issuetype - Listar tipos de issue
  • /rest/api/3/priority - Listar prioridades

Formato de Saída TOON

Por padrão, todas as respostas usam o formato TOON (Token-Oriented Object Notation), que reduz o uso de tokens em 30-60% em comparação com JSON. O TOON usa arrays tabulares e sintaxe mínima, tornando-o ideal para consumo por IA.

Para usar JSON em vez disso: Adicione --output-format json aos comandos CLI ou defina outputFormat: "json" nas chamadas de ferramentas MCP.

Exemplo TOON vs JSON:

TOON: key|summary|status
      PROJ-1|First issue|Open
      PROJ-2|Second issue|Done

JSON: [{"key":"PROJ-1","summary":"First issue","status":"Open"},
       {"key":"PROJ-2","summary":"Second issue","status":"Done"}]

Filtragem com JMESPath

Todas as ferramentas suportam filtragem opcional com JMESPath (jq) para extrair dados específicos:

# Get just project names and keys
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/project/search" \
  --jq "values[].{key: key, name: name}"

# Get issue key and summary
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"

Truncamento de Respostas e Logs Brutos

Para respostas grandes de API (>40 mil caracteres ≈ 10 mil tokens), as respostas são truncadas automaticamente com orientação. A resposta bruta completa é salva em /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt para referência.

Quando truncado, você verá:

  • Um aviso de truncamento com o caminho do arquivo bruto
  • Sugestões para refinar sua consulta com melhores filtros
  • Percentual de dados exibidos em relação ao tamanho total

Exemplos do Mundo Real

Explore Seus Projetos

Pergunte ao seu assistente de IA:

  • "Liste todos os projetos aos quais tenho acesso"
  • "Mostre-me detalhes sobre o projeto DEV"
  • "Quais projetos contêm a palavra 'Platform'?"

Pesquise e Acompanhe Issues

Pergunte ao seu assistente de IA:

  • "Encontre todas as issues de alta prioridade no projeto DEV"
  • "Mostre-me issues atribuídas a mim que estão em andamento"
  • "Pesquise bugs reportados na última semana"
  • "Liste todas as issues abertas para o time mobile"

Gerencie Detalhes de Issues

Pergunte ao seu assistente de IA:

  • "Obtenha detalhes completos sobre a issue PROJ-456 incluindo comentários"
  • "Qual é o status atual e o responsável da PROJ-123?"
  • "Exiba todos os comentários sobre o bug de autenticação"

Comunicação de Issues

Pergunte ao seu assistente de IA:

  • "Adicione um comentário à PROJ-456: 'Revisão de código concluída, pronto para testes'"
  • "Comente sobre a issue de login que ela foi implantada em staging"

Comandos CLI

A CLI espelha as ferramentas MCP para acesso direto pelo terminal:

# GET request (returns TOON format by default)
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# GET with query parameters and JSON output
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "project=DEV AND status=\"In Progress\"", "maxResults": "10"}' \
  --output-format json

# GET with JMESPath filtering to extract specific fields
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"

# POST request (create an issue)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue" \
  --body '{"fields": {"project": {"key": "DEV"}, "summary": "New issue title", "issuetype": {"name": "Task"}}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue/PROJ-123/comment" \
  --body '{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "My comment"}]}]}}'

# PUT request (update issue - full replacement)
npx -y @aashari/mcp-server-atlassian-jira put \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-jira patch \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-jira delete \
  --path "/rest/api/3/issue/PROJ-123/comment/12345"

Observação: Todos os comandos CLI suportam:

  • --output-format - Escolha entre toon (padrão, eficiente em tokens) ou json
  • --jq - Filtrar resposta com expressões JMESPath
  • --query-params - Passar parâmetros de consulta como string JSON

Solução de Problemas

"Falha na autenticação" ou "403 Forbidden"

  1. Verifique as permissões do seu Token de API:

  2. Verifique o formato do nome do seu site:

    • Se sua URL do Jira é https://mycompany.atlassian.net
    • Seu nome de site deve ser apenas mycompany

  3. Teste suas credenciais:

    npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself"

"Recurso não encontrado" ou "404"

  1. Verifique o caminho da API:

    • Os caminhos diferenciam maiúsculas de minúsculas
    • Use chaves de projeto (por exemplo, DEV) em vez de nomes de projetos
    • Chaves de issue incluem o prefixo do projeto (por exemplo, DEV-123)

  2. Verifique as permissões de acesso:

    • Certifique-se de ter acesso ao projeto no seu navegador
    • Alguns projetos podem ser restritos a determinados usuários

"Nenhum resultado encontrado" ao pesquisar

  1. Tente termos de pesquisa diferentes:

    • Use chaves de projeto em vez de nomes de projetos
    • Tente critérios de pesquisa mais amplos

  2. Verifique a sintaxe JQL:

    • Valide seu JQL na pesquisa avançada do Jira primeiro

Problemas de Integração com o Claude Desktop

  1. Reinicie o Claude Desktop após atualizar o arquivo de configuração
  2. Verifique o local do arquivo de configuração:
    • macOS: ~/.claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

Obtendo Ajuda

Se você ainda estiver com problemas:

  1. Execute um comando de teste simples para verificar se tudo funciona
  2. Verifique as GitHub Issues para problemas semelhantes
  3. Crie uma nova issue com sua mensagem de erro e detalhes da configuração

Perguntas Frequentes

Quais permissões eu preciso?

Sua conta Atlassian precisa de:

  • Acesso ao Jira com as permissões apropriadas para os projetos que você deseja consultar
  • Token de API com permissões apropriadas (concedido automaticamente quando você cria um)

Posso usar isso com o Jira Server (on-premise)?

Atualmente, esta ferramenta suporta apenas Jira Cloud. O suporte para Jira Server/Data Center pode ser adicionado em versões futuras.

Como encontro meu nome de site?

Seu nome de site é a primeira parte da sua URL do Jira:

  • URL: https://mycompany.atlassian.net -> Nome do site: mycompany
  • URL: https://acme-corp.atlassian.net -> Nome do site: acme-corp

Com quais assistentes de IA isso funciona?

Qualquer assistente de IA que suporte o Model Context Protocol (MCP):

  • Claude Desktop
  • Cursor AI
  • Continue.dev
  • Muitos outros

Meus dados estão seguros?

Sim! Esta ferramenta:

  • É executada inteiramente na sua máquina local
  • Usa suas próprias credenciais do Jira
  • Nunca envia seus dados a terceiros
  • Acessa apenas o que você der permissão para acessar

Posso pesquisar em vários projetos?

Sim! Use consultas JQL para pesquisas entre projetos. Por exemplo:

npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "assignee=currentUser() AND status=\"In Progress\""}'

Detalhes Técnicos

Atualizações Recentes

Versão 3.2.1 (Dezembro de 2025):

  • Adicionado formato de saída TOON para redução de 30-60% em tokens
  • Implementado truncamento automático de respostas para payloads grandes (>40 mil caracteres)
  • Respostas brutas da API salvas em /tmp/mcp/mcp-server-atlassian-jira/ para referência
  • Atualizado para MCP SDK v1.23.0 com API moderna registerTool
  • Corrigido endpoint obsoleto /rest/api/3/search (agora use /rest/api/3/search/jql)
  • Atualizadas todas as dependências para as versões mais recentes (Zod v4.1.13, Commander v14.0.2)

Requisitos

  • Node.js: 18.0.0 ou superior
  • MCP SDK: v1.23.0 (usa APIs modernas de registro)
  • Jira: Somente Cloud (Server/Data Center não suportado)

Arquitetura

Este servidor segue a arquitetura MCP de 5 camadas:

  1. Camada CLI - Interface humana usando Commander.js
  2. Camada de Ferramentas - Interface de IA com validação Zod
  3. Camada de Controladores - Lógica de negócio e orquestração
  4. Camada de Serviços - Chamadas diretas à API REST do Jira
  5. Camada de Utilitários - Preocupações transversais (logging, formatação, transporte)

Depuração

Ative o log de depuração definindo a variável de ambiente DEBUG:

# In Claude Desktop config
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "DEBUG": "true",
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Os logs de depuração são gravados em ~/.mcp/data/mcp-server-atlassian-jira.<session-id>.log

Verifique respostas brutas da API: Quando as respostas são truncadas, a resposta bruta completa é salva em /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt com detalhes de request/response.

Migração do v2.x

A versão 3.0 substitui 8+ ferramentas específicas por 5 ferramentas genéricas de métodos HTTP. Se você está atualizando do v2.x:

Antes (v2.x):

jira_ls_projects, jira_get_project, jira_ls_issues, jira_get_issue,
jira_create_issue, jira_ls_comments, jira_add_comment, jira_ls_statuses, ...

Depois (v3.0+):

jira_get, jira_post, jira_put, jira_patch, jira_delete

Exemplos de migração:

  • jira_ls_projects -> jira_get com caminho /rest/api/3/project/search
  • jira_get_project -> jira_get com caminho /rest/api/3/project/{key}
  • jira_get_issue -> jira_get com caminho /rest/api/3/issue/{key}
  • jira_create_issue -> jira_post com caminho /rest/api/3/issue
  • jira_add_comment -> jira_post com caminho /rest/api/3/issue/{key}/comment
  • jira_ls_statuses -> jira_get com caminho /rest/api/3/status

Benefícios do v3.0+:

  • Acesso completo a qualquer endpoint da API REST v3 do Jira (não apenas ferramentas predefinidas)
  • Filtragem JMESPath para extração eficiente de dados
  • Interface consistente em todos os métodos HTTP
  • Formato TOON para economia de 30-60% em tokens
  • Truncamento automático de respostas com registro em arquivo bruto

Suporte

Precisa de ajuda? Veja como obter assistência:

  1. Consulte a seção de solução de problemas acima - os problemas mais comuns estão cobertos lá
  2. Visite nosso repositório GitHub para documentação e exemplos: github.com/aashari/mcp-server-atlassian-jira
  3. Reporte problemas em GitHub Issues
  4. Inicie uma discussão para solicitações de recursos ou perguntas gerais

Feito com carinho para equipes que desejam trazer IA ao seu fluxo de trabalho de gerenciamento de projetos.