MCP-Atlassian: Descrição Detalhada do Projeto

Visão Geral do Projeto

MCP-Atlassian é um servidor baseado no Model Context Protocol (MCP) projetado especificamente para produtos Atlassian (Confluence e Jira). Este projeto permite que assistentes de IA (como o Claude) acessem e manipulem diretamente os dados do seu espaço de trabalho Atlassian, possibilitando o gerenciamento inteligente do fluxo de trabalho.

Informações Básicas do Projeto

• Nome do Projeto: mcp-atlassian
• Desenvolvedor: sooperset
• Endereço GitHub: https://github.com/sooperset/mcp-atlassian
• Método de Implantação: Contêiner Docker

Principais Características e Funcionalidades

Operações Inteligentes Impulsionadas por IA

O projeto suporta diversas operações inteligentes impulsionadas por assistentes de IA:

• 📝 Atualização Automática do Jira - "Atualize o Jira a partir das nossas atas de reunião"
• 🔍 Pesquisa no Confluence Impulsionada por IA - "Encontre o nosso guia de OKR no Confluence e resuma-o"
• 🐛 Filtragem Inteligente de Problemas do Jira - "Mostre os bugs urgentes do projeto PROJ da semana passada"
• 📄 Criação e Gestão de Conteúdo - "Crie um documento de design técnico para a funcionalidade XYZ"

Suporte de Compatibilidade de Produtos

Produto	Tipo de Implantação	Estado de Suporte
Confluence	Cloud	✅ Totalmente Suportado
Confluence	Server/Data Center	✅ Suportado (versão 6.0+)
Jira	Cloud	✅ Totalmente Suportado
Jira	Server/Data Center	✅ Suportado (versão 8.14+)

Instalação e Configuração

Pré-requisitos

• Ambiente Docker
• Atlassian API Token (versão Cloud) ou Token de Acesso Pessoal (versão Server)

Obtenção de Tokens de Autenticação

Atlassian Cloud:

1. Acesse https://id.atlassian.com/manage-profile/security/api-tokens
2. Clique em "Create API token", nomeie e copie o token

Server/Data Center:

1. Vá para o perfil pessoal → Tokens de Acesso Pessoal
2. Clique em "Create token", defina o tempo de expiração e copie o token

Obtenção da Imagem Docker

# Puxe a imagem pré-construída
docker pull ghcr.io/sooperset/mcp-atlassian:latest

Configuração de Integração IDE

Configuração do Claude Desktop

Localização do arquivo de configuração:

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

Método 1: Passando Variáveis Diretamente

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME", 
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com", 
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

Método 2: Usando um Arquivo de Ambiente

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm", 
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Configuração Server/Data Center

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i", 
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL", 
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat", 
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

Descrição das Variáveis de Ambiente

Variáveis de ambiente comuns:

• CONFLUENCE_SPACES_FILTER: Filtrar por chaves de espaço (ex: "DEV,TEAM,DOC")
• JIRA_PROJECTS_FILTER: Filtrar por chaves de projeto (ex: "PROJ,DEV,SUPPORT")
• READ_ONLY_MODE: Defina como "true" para desativar operações de escrita
• MCP_VERBOSE: Defina como "true" para habilitar logs detalhados
• ENABLED_TOOLS: Lista de nomes de ferramentas separados por vírgula

Funcionalidades de Ferramentas Disponíveis

Ferramentas Confluence

Nome da Ferramenta	Descrição da Funcionalidade
confluence_search	Pesquisar conteúdo do Confluence usando CQL
confluence_get_page	Obter o conteúdo de uma página específica
confluence_get_page_children	Obter as subpáginas de uma página
confluence_get_page_ancestors	Obter as páginas pai de uma página
confluence_get_comments	Obter comentários de uma página
confluence_create_page	Criar uma nova página
confluence_update_page	Atualizar uma página existente
confluence_delete_page	Excluir uma página
confluence_get_labels	Obter etiquetas
confluence_add_label	Adicionar etiqueta

Ferramentas Jira

Nome da Ferramenta	Descrição da Funcionalidade
jira_get_issue	Obter detalhes de um problema específico
jira_search	Pesquisar problemas usando JQL
jira_get_project_issues	Obter problemas de um projeto
jira_get_epic_issues	Obter problemas de épico
jira_create_issue	Criar um novo problema
jira_batch_create_issues	Criar problemas em lote
jira_update_issue	Atualizar um problema existente
jira_delete_issue	Excluir um problema
jira_get_transitions	Obter transições de status de um problema
jira_transition_issue	Transicionar o status de um problema
jira_add_comment	Adicionar um comentário
jira_add_worklog	Adicionar um registro de trabalho
jira_get_worklog	Obter registros de trabalho
jira_download_attachments	Baixar anexos
jira_link_to_epic	Ligar a um épico
jira_get_agile_boards	Obter quadros Kanban
jira_get_board_issues	Obter problemas do quadro Kanban
jira_get_sprints_from_board	Obter sprints do quadro Kanban
jira_get_sprint_issues	Obter problemas da sprint
jira_create_sprint	Criar sprint
jira_update_sprint	Atualizar sprint
jira_get_issue_link_types	Obter tipos de links de problemas
jira_create_issue_link	Criar link de problema
jira_remove_issue_link	Remover link de problema

Nota: As ferramentas marcadas com * estão disponíveis apenas no Jira Cloud

Controle de Acesso

Filtragem de Ferramentas

Use a flag --enabled-tools ou a variável de ambiente ENABLED_TOOLS para especificar as ferramentas disponíveis:

# Através da variável de ambiente
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# Ou através da flag de linha de comando
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

Controle de Leitura e Escrita

As ferramentas são divididas em operações de leitura e escrita. Quando READ_ONLY_MODE está habilitado, apenas as operações de leitura estão disponíveis, independentemente da configuração de ENABLED_TOOLS.

Resolução de Problemas

Solução de Problemas Comuns

Falha na Autenticação:

• Versão Cloud: Verifique o API token (não a senha da conta)
• Versão Server/Data Center: Verifique se o token de acesso pessoal é válido e não expirou
• Servidores Confluence antigos: Pode ser necessário usar CONFLUENCE_USERNAME e CONFLUENCE_API_TOKEN (o token é a senha)

Problemas com Certificados SSL: Em implantações Server/Data Center, se encontrar erros SSL, defina CONFLUENCE_SSL_VERIFY=false ou JIRA_SSL_VERIFY=false

Erros de Permissão: Certifique-se de que a conta Atlassian tem permissões suficientes para acessar os espaços/projetos relevantes

Métodos de Depuração

Use o MCP Inspector para Testar:

npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

Verifique os Logs:

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows  
type %APPDATA%\Claude\logs\mcp*.log | more

Usando a Transferência SSE

Além da transferência stdio padrão, o Server-Sent Events (SSE) também é suportado:

1. Inicie o servidor manualmente no terminal:

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

2. Configure o IDE para conectar-se ao servidor em execução:

{
  "mcpServers": {
    "mcp-atlassian-sse": {
      "url": "http://localhost:9000/sse"
    }
  }
}

Considerações de Segurança

• Nunca compartilhe API tokens
• Mantenha os arquivos .env seguros e privados
• Consulte SECURITY.md para obter as melhores práticas

Arquitetura Técnica

O projeto adota a implantação em contêineres Docker, comunicando-se com assistentes de IA através do Model Context Protocol. Suporta vários métodos de transferência (stdio e SSE), permitindo uma adaptação flexível a diferentes ambientes de implantação e cenários de uso.

O design do projeto considera as necessidades de aplicações de nível empresarial, suportando as versões Cloud e de implantação privada do Atlassian, fornecendo autenticação completa, controle de permissões e mecanismos de segurança.

---

Atenção: Este não é um produto oficial da Atlassian, mas sim um projeto de código aberto mantido pelo desenvolvedor da comunidade sooperset.