Atlassian-mcp-server

Servidor MCP para Atlassian Cloud (Confluence e Jira) com autenticação OAuth 2.0 integrada.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Atlassian MCP Server

PyPI version Python Support License: MIT Code Quality Dependency Security

Servidor MCP para Atlassian Cloud (Confluence e Jira) com autenticação OAuth 2.0 integrada. Este servidor permite que agentes de IA ajudem usuários a documentar trabalho no Confluence, gerenciar issues do Jira e entender o contexto do projeto.

Recursos

  • Fluxo OAuth 2.0 Integrado: Autenticação automática baseada em navegador com segurança PKCE
  • Arquitetura Modular: Classes de cliente especializadas para operações Jira, Confluence e Service Desk
  • Carregamento Seletivo de Módulos: Configure quais módulos carregar usando variáveis de ambiente
  • Integração com Jira: Pesquisar, criar e atualizar issues; adicionar comentários; gerenciar trabalho
  • Integração com Confluence: Pesquisar e ler conteúdo para compreensão de contexto
  • Gerenciamento de Serviços: Acessar tickets de suporte e solicitações
  • Gerenciamento Automático de Tokens: Lida com a renovação de tokens automaticamente
  • Permissões Mínimas: Segue o princípio do menor privilégio com apenas os escopos necessários

Arquitetura

O servidor usa uma arquitetura modular com classes de cliente especializadas:

  • BaseAtlassianClient: Autenticação OAuth 2.0 principal e manipulação de requisições HTTP
  • JiraClient: Operações específicas do Jira (issues, projetos, comentários)
  • ConfluenceClient: Operações específicas do Confluence (páginas, espaços, pesquisa)
  • ServiceDeskClient: Operações de Gerenciamento de Serviços (solicitações, aprovações, CMDB de Ativos)

Cada módulo pode ser habilitado/desabilitado de forma independente para desempenho e segurança ideais.

Casos de Uso

Este servidor MCP foi projetado para ajudar agentes de IA a auxiliar usuários com:

  • Documentação de Trabalho: Ajudar a documentar progresso do trabalho e decisões no Confluence
  • Gerenciamento de Issues: Criar, atualizar e acompanhar issues do Jira com base em conversas
  • Compreensão de Contexto: Ler páginas do Confluence para entender o histórico do projeto
  • Registro de Tempo e Atividades: Acompanhar atividades de trabalho e tempo gasto em tarefas
  • Solicitações de Serviço: Acessar tickets de gerenciamento de serviços para contexto de suporte
  • Coordenação de Projetos: Pesquisar no Jira e no Confluence por informações do projeto

Configuração do App OAuth

1. Criar App OAuth

  1. Acesse o Console de Desenvolvedor Atlassian
  2. Clique em Create → OAuth 2.0 integration
  3. Digite o nome do seu app e aceite os termos
  4. Defina a Callback URL como: http://localhost:8080/callback

2. Configurar Escopos Necessários

IMPORTANTE: Você deve adicionar exatamente estes escopos ao seu app OAuth antes que o servidor MCP possa funcionar corretamente.

Escopos da API do Jira

Navegue até Permissions → Jira API e adicione:

  • read:jira-work - Ler issues, projetos e pesquisas
  • read:jira-user - Ler informações do usuário
  • write:jira-work - Criar e atualizar issues

Escopos da API do Confluence

Navegue até Permissions → Confluence API e adicione:

  • read:page:confluence - Ler conteúdo de páginas (escopo granular para API v2)
  • read:space:confluence - Ler informações de espaços (escopo granular para API v2)
  • write:page:confluence - Criar e atualizar páginas (escopo granular para API v2)

Escopos da API de Gerenciamento de Serviços

Navegue até Permissions → Jira Service Management API e adicione:

  • read:servicedesk-request - Ler solicitações de gerenciamento de serviços
  • write:servicedesk-request - Criar e atualizar solicitações de gerenciamento de serviços
  • manage:servicedesk-customer - Gerenciar clientes e participantes do service desk
  • read:knowledgebase:jira-service-management - Pesquisar artigos da base de conhecimento

Escopos da API de Identidade do Usuário

Navegue até Permissions → User identity API e adicione:

  • read:me - Informações do perfil do usuário

Escopos Principais

Estes geralmente estão disponíveis por padrão:

  • offline_access - Capacidade de renovação de token

3. Instalar o App no Seu Site Atlassian

Após configurar os escopos, você precisa instalar o app no seu site Atlassian:

  1. No seu app OAuth, vá até a aba Authorization
  2. Use o gerador de URL de autorização para criar uma URL de instalação:
    • Selecione os escopos configurados
    • Escolha seu site Atlassian no menu suspenso
    • Clique em Generate URL
  3. Acesse a URL gerada no seu navegador para instalar o app no seu site
  4. Conceda as permissões quando solicitado pela Atlassian

Observação: Esta etapa é necessária antes que o servidor MCP possa acessar seus dados do Atlassian. O app deve ser instalado e autorizado para o seu site específico.

4. Obter Suas Credenciais

Após instalar o app:

  1. Vá até a aba Settings no seu app OAuth
  2. Copie seu Client ID e Client Secret
  3. Defina as variáveis de ambiente (veja a seção de Configuração abaixo)

5. Resumo da Configuração de Escopos

Mínimo Necessário (12 escopos):

read:jira-work
read:jira-user  
write:jira-work
read:page:confluence
read:space:confluence
write:page:confluence
read:servicedesk-request
write:servicedesk-request
manage:servicedesk-customer
read:knowledgebase:jira-service-management
read:me
offline_access

Opcional (adicione apenas se necessário):

write:servicedesk-request      # Only if creating service tickets
manage:* scopes                # Only for administrative operations

6. Solução de Problemas com Escopos

Se você receber erros relacionados a escopos:

  • "scope does not match": O escopo não foi adicionado ao seu app OAuth no Console de Desenvolvedor
  • "Current user not permitted": O usuário não tem permissões de nível de produto (entre em contato com seu administrador Atlassian)
  • "Unauthorized": Verifique se todos os escopos necessários estão configurados corretamente

Observação: Após adicionar novos escopos ao seu app OAuth, você deve reautenticar usando a ferramenta authenticate_atlassian para obter tokens novos com as novas permissões.

Instalação

Pré-requisitos

  • Python 3.8 ou superior
  • Gerenciador de pacotes pip3
  • Acesso a um site Atlassian Cloud
  • App OAuth configurado (veja Configuração do App OAuth acima)

Instalar a partir do PyPI (Recomendado)

pip3 install atlassian-mcp-server

Instalar a partir do Repositório GitHub

# Install directly from GitHub repository
pip3 install git+https://github.com/rorymcmahon/atlassian-mcp-server.git

Instalar a partir do Código-Fonte

# Clone the repository
git clone https://github.com/rorymcmahon/atlassian-mcp-server.git
cd atlassian-mcp-server

# Install in development mode
pip3 install -e .

Verificar a Instalação

# Check that the command is available
atlassian-mcp-server --help

# Or check the Python module
python -m atlassian_mcp_server --help

Configuração

Defina as seguintes variáveis de ambiente:

export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_CLIENT_ID="your-oauth-client-id"
export ATLASSIAN_CLIENT_SECRET="your-oauth-client-secret"

Configuração Opcional

Seleção de Módulos: Controle quais módulos são carregados (padrão: todos os módulos habilitados):

export ATLASSIAN_MODULES="jira,confluence,service_desk"  # Enable specific modules
export ATLASSIAN_MODULES="jira,confluence"              # Enable only Jira and Confluence
export ATLASSIAN_MODULES="jira"                         # Enable only Jira

Módulos disponíveis:

  • jira - Gerenciamento de issues do Jira e operações de projetos
  • confluence - Operações de páginas e espaços do Confluence
  • service_desk - Operações de Gerenciamento de Serviços e CMDB de Ativos

Observação: Desabilitar módulos não utilizados reduz o uso de memória e melhora o tempo de inicialização.

Uso

# Start the MCP server
python -m atlassian_mcp_server

# Or run directly
python src/atlassian_mcp_server/server.py

Configuração do Cliente MCP

Observação: Todos os exemplos de configuração abaixo mostram as variáveis de ambiente necessárias. Você pode opcionalmente adicionar "ATLASSIAN_MODULES": "jira,confluence,service_desk" a qualquer seção env para controlar quais módulos são carregados.

Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Amazon Q Developer CLI

Crie um arquivo de configuração do agente:

Arquivo: ~/.aws/amazonq/cli-agents/atlassian.json

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "atlassian",
  "description": "Atlassian Jira and Confluence integration agent",
  "prompt": "You are an AI assistant with access to Atlassian Jira and Confluence. Help users manage issues, search content, and document their work.",
  "mcpServers": {
    "atlassian-mcp-server": {
      "command": "atlassian-mcp-server",
      "args": [],
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      },
      "autoApprove": ["*"],
      "disabled": false,
      "timeout": 60000,
      "initTimeout": 120000
    }
  },
  "tools": [
    "@atlassian-mcp-server/*"
  ],
  "allowedTools": [
    "@atlassian-mcp-server/*"
  ]
}

Em seguida, use: q chat --agent atlassian

VS Code com Continue

Adicione à sua configuração do Continue:

Arquivo: ~/.continue/config.json

{
  "models": [...],
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

VS Code com GitHub Copilot Chat

Para GitHub Copilot Chat com suporte a MCP, adicione às configurações do workspace:

Arquivo: .vscode/settings.json

{
  "github.copilot.chat.mcp.servers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Cline (Extensão do VS Code)

Adicione à configuração MCP do Cline:

Arquivo: ~/.cline/mcp_servers.json

{
  "atlassian": {
    "command": "atlassian-mcp-server",
    "env": {
      "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
      "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
      "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
    }
  }
}

Configuração de Variáveis de Ambiente

Por segurança, defina variáveis de ambiente em vez de codificá-las nos arquivos de configuração:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_CLIENT_ID="your-oauth-client-id"
export ATLASSIAN_CLIENT_SECRET="your-oauth-client-secret"

Em seguida, use nas configurações:

{
  "env": {
    "ATLASSIAN_SITE_URL": "${ATLASSIAN_SITE_URL}",
    "ATLASSIAN_CLIENT_ID": "${ATLASSIAN_CLIENT_ID}",
    "ATLASSIAN_CLIENT_SECRET": "${ATLASSIAN_CLIENT_SECRET}"
  }
}

Fluxo de Autenticação

  1. Inicie o servidor MCP
  2. Use a ferramenta authenticate_atlassian para iniciar o fluxo OAuth
  3. O navegador abre automaticamente no login da Atlassian
  4. Após a autorização, a autenticação é concluída automaticamente
  5. As credenciais são salvas localmente para uso futuro

Ferramentas Disponíveis

Autenticação

  • authenticate_atlassian() - Iniciar fluxo de autenticação OAuth integrado

Operações do Jira

  • jira_search(jql, max_results=50) - Pesquisar issues com JQL
  • jira_get_issue(issue_key) - Obter detalhes de uma issue específica
  • jira_create_issue(project_key, summary, description, issue_type="Task") - Criar nova issue
  • jira_update_issue(issue_key, summary=None, description=None) - Atualizar issue existente
  • jira_add_comment(issue_key, comment) - Adicionar comentário a uma issue

Operações do Confluence

Gerenciamento Principal de Conteúdo

  • confluence_search(query, limit=10) - Pesquisar conteúdo no Confluence
  • confluence_get_page(page_id) - Obter conteúdo de uma página específica
  • confluence_create_page(space_key, title, content, parent_id=None) - Criar nova página no Confluence
  • confluence_update_page(page_id, title, content, version) - Atualizar página existente no Confluence

Gerenciamento de Espaços

  • confluence_list_spaces(limit=25, space_type=None, status="current") - Listar espaços disponíveis
  • confluence_get_space(space_id, include_icon=False) - Obter informações detalhadas de um espaço
  • confluence_get_space_pages(space_id, limit=25, status="current") - Obter páginas de um espaço

Pesquisa e Descoberta Aprimoradas

  • confluence_search_content(query, limit=25, space_id=None) - Pesquisa avançada de conteúdo
  • confluence_get_page_children(page_id, limit=25) - Obter páginas filhas

Comentários e Colaboração

  • confluence_get_page_comments(page_id, limit=25) - Obter comentários de uma página
  • confluence_add_comment(page_id, comment, parent_comment_id=None) - Adicionar comentário a uma página
  • confluence_get_comment(comment_id) - Obter detalhes de um comentário específico

Rótulos e Organização

  • confluence_get_page_labels(page_id, limit=25) - Obter rótulos de uma página
  • confluence_search_by_label(label_id, limit=25) - Encontrar páginas com um rótulo específico
  • confluence_list_labels(limit=25, prefix=None) - Listar todos os rótulos disponíveis

Anexos

  • confluence_get_page_attachments(page_id, limit=25) - Obter anexos de uma página
  • confluence_get_attachment(attachment_id) - Obter detalhes de um anexo

Histórico de Versões

  • confluence_get_page_versions(page_id, limit=25) - Obter histórico de versões de uma página
  • confluence_get_page_version(page_id, version_number) - Obter uma versão específica de uma página

Operações de Gerenciamento de Serviços

Ferramentas de Descoberta (Essenciais para Agentes de IA)

  • servicedesk_check_availability() - Verificar se o Jira Service Management está configurado
  • servicedesk_list_service_desks(limit=50) - Listar service desks disponíveis para criar solicitações
  • servicedesk_get_service_desk(service_desk_id) - Obter informações detalhadas do service desk
  • servicedesk_list_request_types(service_desk_id=None, limit=50) - Listar tipos de solicitação disponíveis
  • servicedesk_get_request_type(service_desk_id, request_type_id) - Obter informações detalhadas do tipo de solicitação
  • servicedesk_get_request_type_fields(service_desk_id, request_type_id) - Obter campos obrigatórios/opcionais para o tipo de solicitação

Gerenciamento de Solicitações

  • servicedesk_get_requests(service_desk_id=None, limit=50) - Obter solicitações do service desk
  • servicedesk_get_request(issue_key) - Obter detalhes de uma solicitação específica do service desk
  • servicedesk_create_request(service_desk_id, request_type_id, summary, description) - Criar nova solicitação de serviço
  • servicedesk_add_comment(issue_key, comment, public=True) - Adicionar comentário a uma solicitação de serviço
  • servicedesk_get_request_comments(issue_key, limit=50) - Obter comentários de uma solicitação de serviço
  • servicedesk_get_request_status(issue_key) - Obter status de uma solicitação de serviço
  • servicedesk_get_request_transitions(issue_key) - Obter transições de status disponíveis para a solicitação
  • servicedesk_transition_request(issue_key, transition_id, comment=None) - Transicionar solicitação para um novo status

Gerenciamento de Aprovações e Participantes

  • servicedesk_get_approvals(issue_key) - Obter informações de aprovação da solicitação
  • servicedesk_approve_request(issue_key, approval_id, decision) - Aprovar ou recusar aprovação de solicitação
  • servicedesk_get_participants(issue_key) - Obter participantes da solicitação
  • servicedesk_add_participants(issue_key, usernames) - Adicionar participantes à solicitação (com prompts de confirmação)
  • servicedesk_manage_notifications(issue_key, subscribe) - Assinar/cancelar assinatura de notificações da solicitação

Solução de Problemas

Problemas de Autenticação

  • Certifique-se de que a URI de redirecionamento corresponda exatamente: http://localhost:8080/callback
  • Verifique se todos os escopos necessários estão configurados no Console de Desenvolvedor Atlassian
  • Verifique se as variáveis de ambiente estão definidas corretamente

Problemas de Permissão

  • Certifique-se de que seu usuário tenha acesso apropriado ao Jira e ao Confluence
  • Verifique se o app OAuth tem todos os escopos necessários habilitados
  • Verifique se o usuário está nos grupos corretos (por exemplo, confluence-users)

Erros de API

  • Verifique se a URL do seu site Atlassian está correta
  • Certifique-se de ter permissões adequadas para os recursos que está acessando
  • Execute os scripts de teste para verificar a funcionalidade

Requisitos de Escopos

Este servidor MCP usa escopos mínimos necessários seguindo o princípio do menor privilégio:

Escopos Essenciais (16 no total)

  • Jira: read:jira-work, read:jira-user, write:jira-work
  • Confluence: read:page:confluence, read:space:confluence, write:page:confluence, read:comment:confluence, write:comment:confluence, read:label:confluence, read:attachment:confluence
  • Gerenciamento de Serviços: read:servicedesk-request, write:servicedesk-request, manage:servicedesk-customer, read:knowledgebase:jira-service-management
  • Principais: read:me, offline_access

Escopos Opcionais (adicione apenas se necessário)

  • Escopos manage:* - Apenas para operações administrativas

Importante: Escopos Granulares para API v2

Este servidor MCP usa escopos granulares para operações do Confluence para garantir compatibilidade com os endpoints da API v2 do Confluence. A API v2 oferece melhor desempenho e preparação para o futuro em comparação com a API REST v1 descontinuada.

Escopos Granulares vs. Clássicos:

  • Granular (recomendado): read:page:confluence, write:page:confluence - Funciona com a API v2
  • Clássico (descontinuado): read:confluence-content.all, write:confluence-content - Funciona apenas com a API v1

Se você configurou escopos clássicos anteriormente, precisará atualizar seu app OAuth para usar escopos granulares e reautenticar para obter tokens novos.

Segurança da Cadeia de Suprimentos

Este projeto implementa medidas abrangentes de segurança na cadeia de suprimentos:

Gerenciamento de Dependências

  • Versões Fixadas: Todas as dependências usam versões exatas fixadas para evitar atualizações inesperadas
  • Verificação de Segurança: Verificação automatizada de vulnerabilidades com Safety e pip-audit
  • Rastreamento de Dependências: Documentação completa de dependências em docs/DEPENDENCIES.md
  • Atualizações Regulares: Verificações de segurança automatizadas semanais via GitHub Actions

Ferramentas de Segurança

# Generate dependency report
python3 scripts/generate_dependency_report.py

# Check for vulnerabilities
pip3 install safety pip-audit
safety check
pip-audit

# Update dependencies safely
python3 scripts/update_dependencies.py

Arquivos

  • requirements.txt - Dependências de produção fixadas
  • docs/DEPENDENCIES.md - Relatório de dependências legível por humanos
  • docs/dependency-report.json - Dados de dependências legíveis por máquina
  • SECURITY.md - Política de segurança e resposta a vulnerabilidades
  • .github/workflows/dependency-security.yml - Verificações de segurança automatizadas

Desenvolvimento

O servidor é construído usando:

  • FastMCP: Framework moderno de servidor MCP
  • httpx: Cliente HTTP assíncrono
  • Pydantic: Validação de dados e gerenciamento de configurações

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.