MCP Jira Integration

MCP Jira Integration

Um servidor simples de Model Context Protocol (MCP) para Jira que permite que LLMs atuem como gerentes de projeto e assistentes pessoais para equipes que usam Jira. Construído sobre a Jira REST API v3.

Recursos

Ferramentas MCP Principais

• create_issue - Cria novas issues do Jira com formatação adequada e descrições ADF
• search_issues - Pesquisa issues usando JQL com formatação inteligente e paginação
• get_sprint_status - Obtém relatórios abrangentes de progresso do sprint com métricas
• get_team_workload - Analisa cargas de trabalho e capacidade dos membros da equipe
• generate_standup_report - Gera relatórios diários de standup automaticamente

Capacidades de Gerenciamento de Projetos

• Suporte a Múltiplos Projetos: Trabalhe com vários projetos especificando chaves de projeto dinamicamente
• Acompanhamento de progresso do sprint com indicadores visuais
• Análise de carga de trabalho da equipe e planejamento de capacidade
• Geração automatizada de relatórios diários de standup
• Criação de issues com priorização adequada
• Pesquisa inteligente e filtragem de issues

Confiabilidade

• Repetição automática com backoff exponencial em limites de taxa (429) e erros transitórios (503)
• Paginação para grandes conjuntos de resultados
• Tratamento de datas com consciência de fuso horário
• Tratamento gracioso de status e tipos de issue personalizados do Jira

Requisitos

• Python 3.8 ou superior
• Conta Jira Cloud com token de API
• Cliente compatível com MCP (como Claude Desktop)

Configuração Rápida

1. Clone e instale:

git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Configure as credenciais do Jira:

cp .env.example .env
# Edit .env with your values

JIRA_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your.email@domain.com
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123

3. Teste o servidor:

.venv/bin/python -m mcp_jira

Você deve ver Initializing MCP Jira server... na saída. Pressione Ctrl+C para parar.

Exemplos de Uso

Criando Issues

"Crie um bug de alta prioridade para o sistema de login não funcionando corretamente"

• Atribui automaticamente o tipo de issue, prioridade e formatação adequados

Gerenciamento de Sprint

"Qual é o status do nosso sprint atual?"

• Obtém relatório abrangente de progresso com métricas e indicadores visuais

Gerenciamento de Equipe

"Mostre-me a carga de trabalho da equipe para john.doe, jane.smith, mike.wilson"

• Analisa a capacidade e fornece distribuição de carga de trabalho

Standups Diários

"Gere o relatório de standup de hoje"

• Cria relatório formatado com itens concluídos, em andamento e bloqueados

Integração MCP

Com Claude Desktop

O arquivo de configuração está localizado em:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione a seguinte entrada, substituindo /path/to/mcp-jira pelo caminho absoluto onde você clonou o repositório:

{
  "mcpServers": {
    "mcp-jira": {
      "command": "/path/to/mcp-jira/.venv/bin/python",
      "args": ["-m", "mcp_jira"]
    }
  }
}

Nota: Use o binário Python de dentro da pasta .venv — isso garante que todas as dependências estejam disponíveis. O campo cwd não é necessário; o servidor resolve sua configuração usando caminhos absolutos internamente.

Para encontrar o caminho correto, execute isto de dentro do diretório do projeto:

echo "$(pwd)/.venv/bin/python"

Reinicie o Claude Desktop após salvar a configuração.

Com Outros Clientes MCP

O servidor segue o protocolo MCP padrão e funciona com qualquer cliente compatível com MCP.

Configuração

Variáveis de Ambiente Obrigatórias

• JIRA_URL - URL da sua instância Jira
• JIRA_USERNAME - Seu nome de usuário/e-mail do Jira
• JIRA_API_TOKEN - Seu token de API do Jira
• PROJECT_KEY - Chave de projeto padrão para operações (pode ser substituída por solicitação)

Configurações Opcionais

• DEFAULT_BOARD_ID - Board padrão para operações de sprint (pode ser substituído por solicitação)
• STORY_POINTS_FIELD - ID de campo personalizado para Story Points (padrão: customfield_10026)
• DEBUG_MODE - Ativar log de depuração (padrão: false)
• LOG_LEVEL - Nível de log (padrão: INFO)

Obtendo o Token de API do Jira

1. Vá para Atlassian Account Settings
2. Clique em "Create API token"
3. Dê um nome e copie o token
4. Use seu e-mail como nome de usuário e o token como senha

Arquitetura

Esta implementação prioriza simplicidade e confiabilidade:

• Arquivo único de servidor MCP - Todas as ferramentas em um só lugar
• Protocolo MCP padrão - Usa o SDK oficial do MCP
• Jira REST API v3 - Usa o Atlassian Document Format (ADF) para descrições
• Formatação rica - Fornece relatórios bonitos e legíveis
• Repetição com backoff - Lida automaticamente com limites de taxa e erros transitórios da API do Jira
• Paginação - Busca todos os resultados para grandes conjuntos de issues
• Tratamento de erros - Tratamento gracioso de problemas da API do Jira e status personalizados
• Suporte assíncrono - Operações rápidas e responsivas

Solução de Problemas

Problemas Comuns

1. "Nenhum sprint ativo encontrado"

   • Certifique-se de que seu board tenha um sprint ativo
   • Verifique se DEFAULT_BOARD_ID está configurado corretamente

2. Erros de autenticação

   • Verifique se seu token de API está correto
   • Confirme que seu nome de usuário é seu endereço de e-mail

3. Erros de permissão

   • Garanta que seu usuário do Jira tenha permissões adequadas no projeto
   • Verifique se a chave do projeto existe e se você tem acesso

Modo de Depuração

Defina DEBUG_MODE=true no seu arquivo .env para log detalhado.

Desenvolvimento

1. Faça um fork do repositório
2. Configure um ambiente de desenvolvimento:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. Execute os testes:

python -m pytest tests/ -v

4. Envie um pull request

Licença

Licença MIT - veja o arquivo LICENSE