JIRA

Acesse e gerencie issues, projetos e usuários do JIRA com cargas de dados otimizadas para janelas de contexto de IA.

GitHub
29
Experimente este MCPPatrocinado

Documentação

Servidor MCP JIRA

Uma implementação de servidor Model Context Protocol (MCP) que fornece acesso a dados do JIRA com rastreamento de relacionamentos, payloads de dados otimizados e limpeza de dados para janelas de contexto de IA.

ℹ️ Existe um servidor MCP separado para Confluence

Suporte a Jira Cloud e Jira Server (Data Center)

Este servidor MCP suporta instâncias Jira Cloud e Jira Server (Data Center). Você pode selecionar qual tipo usar definindo a variável de ambiente JIRA_TYPE:

  • cloud (padrão): Para Jira Cloud (hospedado pela Atlassian)
  • server: Para Jira Server/Data Center (auto-hospedado)

O servidor usará automaticamente a versão correta da API e o método de autenticação para o tipo selecionado.

Recursos

  • Pesquisar issues do JIRA usando JQL (máximo de 50 resultados por solicitação)
  • Recuperar filhos de épicos com histórico de comentários e payloads otimizados (máximo de 100 issues por solicitação)
  • Obter informações detalhadas de issues, incluindo comentários e issues relacionadas
  • Criar, atualizar e gerenciar issues do JIRA
  • Adicionar comentários a issues
  • Extrair menções de issues do Formato de Documento Atlassian
  • Rastrear relacionamentos de issues (menções, links, pai/filho, épicos)
  • Limpar e transformar conteúdo rico do JIRA para eficiência de contexto de IA
  • Suporte para anexos de arquivos com manipulação segura de upload multipart
  • Suporta APIs do Jira Cloud e Jira Server (Data Center)

Pré-requisitos

  • Bun (v1.0.0 ou superior)
  • Conta JIRA com acesso à API

Variáveis de Ambiente

JIRA_API_TOKEN=your_api_token            # API token for Cloud, PAT or password for Server/DC
JIRA_BASE_URL=your_jira_instance_url     # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email               # Your Jira account email
JIRA_TYPE=cloud                          # 'cloud' or 'server' (optional, defaults to 'cloud')
JIRA_AUTH_TYPE=basic                     # 'basic' or 'bearer' (optional, defaults to 'basic')

Métodos de Autenticação

  • Jira Cloud: Use tokens de API com autenticação Basic

  • Jira Server/Data Center:

    • Autenticação Basic: Use nome de usuário/senha ou tokens de API
      • Defina JIRA_AUTH_TYPE=basic (padrão)
    • Autenticação Bearer: Use Tokens de Acesso Pessoal (PATs) - disponível no Data Center 8.14.0+
      • Crie um PAT nas configurações do seu perfil
      • Defina JIRA_AUTH_TYPE=bearer
      • Use o PAT como seu JIRA_API_TOKEN

Instalação e Configuração

1. Clone o repositório

git clone [repository-url]
cd jira-mcp

2. Instale as dependências e faça o build

bun install
bun run build

3. Configure o servidor MCP

Edite o arquivo de configuração apropriado:

macOS:

  • Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

  • Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

  • Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Claude Desktop: infelizmente ainda não existe

Adicione a seguinte configuração sob o objeto mcpServers:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email",
        "JIRA_TYPE": "cloud",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

4. Reinicie o servidor MCP

Nas configurações de MCP do Cline, reinicie o servidor MCP. Reinicie o Claude Desktop para carregar o novo servidor MCP.

Desenvolvimento

Execute os testes:

bun test

Modo de observação para desenvolvimento:

bun run dev

Para recompilar após alterações:

bun run build

Ferramentas MCP Disponíveis

search_issues

Pesquisar issues do JIRA usando JQL. Retorna até 50 resultados por solicitação.

Esquema de Entrada:

{
  searchString: string; // JQL search string
}

get_epic_children

Obter todas as issues filhas em um épico, incluindo seus comentários e dados de relacionamento. Limitado a 100 issues por solicitação.

Esquema de Entrada:

{
  epicKey: string; // The key of the epic issue
}

get_issue

Obter informações detalhadas sobre uma issue específica do JIRA, incluindo comentários e todos os relacionamentos.

Esquema de Entrada:

{
  issueId: string; // The ID or key of the JIRA issue
}

create_issue

Criar uma nova issue do JIRA com campos especificados.

Esquema de Entrada:

{
  projectKey: string, // The project key where the issue will be created
  issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
  summary: string, // The issue summary/title
  description?: string, // Optional issue description
  fields?: { // Optional additional fields
    [key: string]: any
  }
}

update_issue

Atualizar campos de uma issue existente do JIRA.

Esquema de Entrada:

{
  issueKey: string, // The key of the issue to update
  fields: { // Fields to update
    [key: string]: any
  }
}

add_attachment

Adicionar um anexo de arquivo a uma issue do JIRA.

Esquema de Entrada:

{
  issueKey: string, // The key of the issue
  fileContent: string, // Base64 encoded file content
  filename: string // Name of the file to be attached
}

add_comment

Adicionar um comentário a uma issue do JIRA. Aceita texto simples e o converte internamente para o Formato de Documento Atlassian necessário.

Esquema de Entrada:

{
  issueIdOrKey: string, // The ID or key of the issue to add the comment to
  body: string // The content of the comment (plain text)
}

Recursos de Limpeza de Dados

  • Extrai texto do Formato de Documento Atlassian
  • Rastreia menções de issues em descrições e comentários
  • Mantém links formais de issues com tipos de relacionamento
  • Preserva relacionamentos pai/filho
  • Rastreia associações de épicos
  • Inclui histórico de comentários com informações do autor
  • Remove metadados desnecessários das respostas
  • Processa recursivamente nós de conteúdo para menções
  • Remove duplicatas de menções de issues

Detalhes Técnicos

  • Construído com TypeScript em modo estrito
  • Usa o runtime Bun para melhor desempenho
  • Vite para builds otimizados
  • Usa a API REST do JIRA v3 (Cloud) ou v2 (Server/Data Center)
  • Suporta múltiplos métodos de autenticação:
    • Autenticação Basic com tokens de API ou nome de usuário/senha
    • Autenticação Bearer com Tokens de Acesso Pessoal (PATs)
  • Solicitações de API em lote para dados relacionados
  • Payloads de resposta otimizados para janelas de contexto de IA
  • Transformação eficiente de estruturas Atlassian complexas
  • Tratamento robusto de erros
  • Considerações de limitação de taxa
  • Limites máximos:
    • Resultados de pesquisa: 50 issues por solicitação
    • Filhos de épicos: 100 issues por solicitação
  • Suporte para dados de formulário multipart para anexos de arquivos seguros
  • Detecção e validação automática de tipo de conteúdo

Tratamento de Erros

O servidor implementa uma estratégia abrangente de tratamento de erros:

  • Detecção de erros de rede e mensagens apropriadas
  • Tratamento de códigos de status HTTP (especialmente 404 para issues)
  • Mensagens de erro detalhadas com códigos de status
  • Registro de detalhes de erros no console
  • Validação de entrada para todos os parâmetros
  • Propagação segura de erros através do protocolo MCP
  • Tratamento especializado para erros comuns da API do JIRA
  • Validação Base64 para anexos
  • Tratamento de falhas em solicitações multipart
  • Detecção de limitação de taxa
  • Validação de parâmetros de anexos

LICENÇA

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENÇA para detalhes.