atlassian-confluence-mcp-server

Servidor MCP do Atlassian Confluence

Um servidor Model Context Protocol (MCP) de código aberto para Atlassian Confluence que permite que assistentes de IA como Claude e Windsurf leiam, criem, pesquisem e gerenciem páginas wiki do Confluence. Funciona com Confluence Cloud, Server local e Data Center — conecte seu agente de IA de codificação à base de conhecimento da sua equipe em segundos via npx.

Por que usar o atlassian-confluence-mcp-server?

• ✅ Único servidor MCP que suporta Cloud + Server + Data Center em um único pacote
• ✅ 47 ferramentas — o MCP de Confluence mais abrangente disponível
• ✅ Zero configuração via npx — sem necessidade de instalação
• ✅ Suporte a PAT, Autenticação Básica e token de API
• ✅ Mantido ativamente com versões assinadas com proveniência

Por que usar este em vez do servidor MCP oficial da Atlassian?

Recurso	Este pacote	Oficial da Atlassian
Confluence Cloud	✅	✅
Server local	✅	❌
Data Center	✅	❌
Zero configuração via npx	✅	❌
47 ferramentas	✅	~15 ferramentas
Gerenciamento de espaços (criar/excluir)	✅	❌
Copiar/mover páginas	✅	❌
Observadores	✅	❌
Permissões/restrições	✅	❌
Extração de tarefas	✅	❌
Exportação (PDF/Word)	✅	❌
Código aberto	✅ MIT	✅
Funciona offline/intranet	✅	❌

Recursos

• Gerenciamento de Espaços — Criar, excluir, listar e inspecionar espaços
• CRUD de Páginas — Criar, ler, atualizar, excluir, copiar e mover páginas
• Pesquisa — Pesquisa completa por CQL e texto, páginas modificadas recentemente
• Rótulos — Adicionar, listar e remover rótulos de páginas
• Comentários — Ler e publicar comentários em páginas
• Anexos — Listar e enviar anexos de páginas e comentários
• Hierarquia de Páginas — Navegar por relações pai/filho
• Histórico de Versões — Navegar e inspecionar versões de páginas
• Observadores — Visualizar e gerenciar observadores de páginas
• Permissões — Obter e definir restrições de páginas
• Tarefas — Extrair tarefas inline de páginas
• Exportação — Gerar URLs de exportação em PDF/Word
• Espaço Pessoal — Criar páginas no seu espaço pessoal
• Análise de URL — Recuperar conteúdo de página a partir de uma URL do Confluence

Pré-requisitos

• Node.js 22.12+
• Uma instância do Confluence (Cloud ou Server/Data Center 7.9+)
• Credenciais de autenticação (PAT ou nome de usuário/senha)

Instalação

Via npx (sem necessidade de instalação)

npx atlassian-confluence-mcp-server

Instalação global

npm install -g atlassian-confluence-mcp-server

A partir do código-fonte

git clone https://github.com/anuragagrawal0430/atlassian-confluence-mcp-server.git
cd atlassian-confluence-mcp-server
npm install
npm run build

Configuração

Toda a configuração é passada por variáveis de ambiente. Nunca codifique credenciais em texto fixo.

Variável	Obrigatória	Descrição
CONFLUENCE_BASE_URL	Sim	URL raiz da sua instância do Confluence
PAT	Ver abaixo	Token de API (Cloud) ou Token de Acesso Pessoal (Server/DC)
CONFLUENCE_USERNAME	Somente Cloud	E-mail da sua conta Atlassian
CONFLUENCE_PASSWORD	Autenticação alternativa	Senha ou token de API para Autenticação Básica
CONFLUENCE_READ_ONLY	Não	Padrão é true; defina como false para permitir ferramentas de mutação
CONFLUENCE_ENABLE_DESTRUCTIVE_TOOLS	Não	Padrão é false; defina como true para permitir ferramentas de exclusão/mutação de permissões
CONFLUENCE_ENABLED_TOOLS	Não	Lista de permissões opcional separada por vírgulas de nomes de ferramentas a expor
CONFLUENCE_ALLOWED_SPACES	Não	Lista de permissões opcional separada por vírgulas de chaves de espaço para solicitações com spaceKey/destinationSpaceKey
CONFLUENCE_ALLOW_INSECURE_HTTP	Não	Padrão é false; só permite http:// para localhost/loopback quando definido como true
CONFLUENCE_MAX_ATTACHMENT_BYTES	Não	Tamanho máximo de arquivo no lado do cliente para confluence_upload_attachment em bytes (padrão: 52428800 / 50 MB). O Confluence ainda pode impor um limite menor na instância.
CONFLUENCE_UPLOAD_ALLOWED_DIRS	Não	Segurança: Lista de permissões separada por vírgulas de caminhos de diretórios absolutos dos quais uploads de arquivos são permitidos. Vazio por padrão (uploads desabilitados).

Confluence Cloud

Os tokens de API da nuvem são gerados a partir da sua conta Atlassian e exigem tanto o seu e-mail quanto o token:

CONFLUENCE_BASE_URL=https://your-site.atlassian.net
CONFLUENCE_USERNAME=you@example.com
PAT=your-api-token

1. Acesse https://id.atlassian.com/manage-profile/security/api-tokens
2. Clique em Create API token, dê um rótulo e copie o valor
3. Defina CONFLUENCE_USERNAME como o e-mail da sua conta Atlassian
4. Defina PAT como o token de API copiado

Confluence Server / Data Center (7.9+)

Instâncias Server e Data Center usam um Token de Acesso Pessoal com autenticação Bearer. Apenas o token é necessário:

CONFLUENCE_BASE_URL=https://confluence.example.com
PAT=your-personal-access-token

1. Navegue até Profile > Settings > Personal Access Tokens
2. Crie um token com as permissões necessárias
3. Copie o valor do token

Autenticação Básica (alternativa)

Para versões mais antigas do Server sem suporte a PAT, use nome de usuário/senha:

CONFLUENCE_BASE_URL=https://confluence.example.com
CONFLUENCE_USERNAME=your-username
CONFLUENCE_PASSWORD=your-password

Controles de Segurança (importante)

O servidor agora usa padrões seguros para reduzir o raio de explosão de injeção de prompts e o risco de vazamento de credenciais:

• CONFLUENCE_READ_ONLY=true por padrão
  • Ferramentas de mutação são desabilitadas a menos que você defina CONFLUENCE_READ_ONLY=false.
• CONFLUENCE_ENABLE_DESTRUCTIVE_TOOLS=false por padrão
  • confluence_delete_page, confluence_delete_space e confluence_set_page_permissions permanecem desabilitadas a menos que sejam explicitamente habilitadas.
• CONFLUENCE_ENABLED_TOOLS (opcional)
  • Restrinja a exposição a uma lista de permissões explícita de ferramentas.
• CONFLUENCE_ALLOWED_SPACES (opcional)
  • Restrinja solicitações que incluam spaceKey / destinationSpaceKey a um conjunto aprovado.
• CONFLUENCE_ALLOW_INSECURE_HTTP=false por padrão
  • HTTPS é obrigatório a menos que isso seja definido como true.
  • Mesmo quando habilitado, HTTP inseguro é restrito apenas a localhost/loopback.
• CONFLUENCE_MAX_ATTACHMENT_BYTES (opcional, padrão 50 MB)
  • Limita o tamanho de um arquivo do host que confluence_upload_attachment lerá antes de chamar o Confluence.
  • Independente da configuração administrativa de "Tamanho Máximo de Anexo" da instância (não exposta via REST público).
• CONFLUENCE_UPLOAD_ALLOWED_DIRS (opcional, padrão vazio)
  • Restringe explicitamente quais diretórios do host o servidor MCP pode ler arquivos ao enviar anexos.
  • Se não configurado, uploads de arquivos do sistema de arquivos do host são totalmente desabilitados.

Exemplo (habilite gravações seguras, mantenha ferramentas destrutivas desabilitadas):

CONFLUENCE_READ_ONLY=false
CONFLUENCE_ENABLE_DESTRUCTIVE_TOOLS=false

Exemplo (lista de permissões estrita):

CONFLUENCE_ENABLED_TOOLS=confluence_get_page,confluence_search_pages,confluence_get_page_body_chunk

Exemplo (lista de permissões em nível de espaço):

CONFLUENCE_ALLOWED_SPACES=ENG,SECURITY

Configuração do Cliente MCP

Cloud (npx)

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "atlassian-confluence-mcp-server"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://your-site.atlassian.net",
        "CONFLUENCE_USERNAME": "you@example.com",
        "PAT": "your-api-token"
      }
    }
  }
}

Server / Data Center (npx)

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "atlassian-confluence-mcp-server"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.example.com",
        "PAT": "your-personal-access-token"
      }
    }
  }
}

Instalação global

{
  "mcpServers": {
    "confluence": {
      "command": "atlassian-confluence-mcp-server",
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.example.com",
        "PAT": "your-personal-access-token"
      }
    }
  }
}

A partir do código-fonte

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.example.com",
        "PAT": "your-personal-access-token"
      }
    }
  }
}

Ferramentas Disponíveis (47)

Observação: a exposição das ferramentas depende da configuração de segurança. Com o padrão CONFLUENCE_READ_ONLY=true, ferramentas de mutação são intencionalmente ocultas/bloqueadas.

Conexão

Ferramenta	Descrição
confluence_test_connection	Testar conexão com a API do Confluence

Espaços

Ferramenta	Descrição
confluence_get_spaces	Listar todos os espaços
confluence_get_space	Obter detalhes do espaço pela chave
confluence_get_space_by_key	Alias para get_space
confluence_create_space	Criar um novo espaço
confluence_delete_space	Excluir um espaço e todo o seu conteúdo
confluence_get_space_homepage	Obter a página inicial de um espaço

Páginas

Ferramenta	Descrição
confluence_get_pages	Listar páginas, opcionalmente filtradas por espaço
confluence_get_page	Obter página por ID
confluence_get_page_by_title	Obter página por título dentro de um espaço
confluence_create_page	Criar uma nova página
confluence_update_page	Atualizar uma página existente
confluence_patch_page	Correção exata de localizar/substituir no lado do servidor para páginas grandes
confluence_replace_page_range	Substituir intervalo intermediário usando deslocamentos ou números de linha
confluence_append_to_page	Anexar ou prefixar conteúdo no lado do servidor
confluence_get_page_body_chunk	Ler corpo de página grande em blocos de deslocamento/comprimento
confluence_delete_page	Excluir uma página
confluence_copy_page	Copiar uma página, opcionalmente para um espaço diferente
confluence_move_page	Mover uma página para um pai ou espaço diferente

Pesquisa

Ferramenta	Descrição
confluence_search	Pesquisar usando CQL
confluence_search_pages	Pesquisar páginas por texto
confluence_get_recently_modified	Obter páginas modificadas recentemente

Rótulos

Ferramenta	Descrição
confluence_get_page_labels	Obter rótulos em uma página
confluence_add_page_label	Adicionar um rótulo a uma página
confluence_delete_page_label	Remover um rótulo de uma página

Comentários

Ferramenta	Descrição
confluence_get_page_comments	Obter comentários em uma página
confluence_add_page_comment	Adicionar um comentário a uma página

Anexos

Ferramenta	Descrição
confluence_get_page_attachments	Listar anexos em uma página
confluence_get_comment_attachments	Listar anexos em um comentário
confluence_upload_attachment	Enviar/atualizar um arquivo local como anexo de página ou comentário

Hierarquia de Páginas

Ferramenta	Descrição
confluence_get_child_pages	Obter páginas filhas de um pai
confluence_get_page_ancestors	Obter páginas ancestrais

Histórico de Versões

Ferramenta	Descrição
confluence_get_page_versions	Obter histórico de versões da página
confluence_get_page_version	Obter uma versão específica da página

Propriedades

Ferramenta	Descrição
confluence_get_page_properties	Obter propriedades de conteúdo de uma página

Usuário

Ferramenta	Descrição
confluence_get_current_user	Obter usuário autenticado atual

Observadores

Ferramenta	Descrição
confluence_get_page_watchers	Obter usuários que observam uma página
confluence_watch_page	Adicionar usuário atual como observador
confluence_unwatch_page	Remover usuário atual como observador

Permissões

Ferramenta	Descrição
confluence_get_page_permissions	Obter restrições/permissões da página
confluence_set_page_permissions	Definir restrições/permissões da página

Tarefas

Ferramenta	Descrição
confluence_get_page_tasks	Extrair tarefas inline de uma página

Exportação

Ferramenta	Descrição
confluence_export_page	Obter URL de exportação para uma página (PDF ou Word)

Utilitários

Ferramenta	Descrição
confluence_get_page_by_url	Obter página a partir de uma URL do Confluence

Espaço Pessoal

Ferramenta	Descrição
confluence_get_personal_space_key	Obter chave do espaço pessoal do usuário atual
confluence_create_page_in_personal_space	Criar página no espaço pessoal
confluence_create_private_space	Criar um espaço privado

Recursos

URI	Descrição
confluence://spaces	Lista de todos os espaços do Confluence

Exemplos de Consultas CQL

# Pages in a specific space
type=page AND space=TEAM

# Pages with a label
type=page AND label=documentation

# Recently modified pages
type=page AND lastModified > now("-7d")

# Title search
type=page AND title~"Meeting Notes"

# Pages created by current user
type=page AND creator=currentUser()

Formato do Corpo da Página

As páginas usam o formato de armazenamento do Confluence (XHTML):

<p>This is a paragraph.</p>
<h1>Heading 1</h1>
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
<ac:structured-macro ac:name="code">
  <ac:parameter ac:name="language">javascript</ac:parameter>
  <ac:plain-text-body><![CDATA[console.log("Hello");]]></ac:plain-text-body>
</ac:structured-macro>

Editando Páginas Muito Grandes

Quando o corpo de uma página é muito grande (por exemplo, centenas de KB), evite enviar o corpo completo por meio de confluence_update_page.

Fluxo de trabalho recomendado:

1. Use confluence_get_page_body_chunk para inspecionar a parte relevante da página.
2. Use uma das opções:
   • confluence_patch_page para edições exatas de localizar/substituir.
   • confluence_replace_page_range para substituir um intervalo intermediário específico.
   • confluence_append_to_page para atualizações incrementais de anexar/prefixar.

Observações:

• A substituição de intervalo baseada em deslocamento é o modo mais confiável para armazenamento XHTML.
• A substituição baseada em linha exige caracteres de nova linha reais no corpo armazenado.
• Essas ferramentas ainda realizam uma atualização completa do Confluence internamente, mas o corpo completo permanece no lado do servidor.

Segurança

• Credenciais são lidas exclusivamente de variáveis de ambiente — nunca codificadas em texto fixo.
• Validação de entrada — todos os parâmetros fornecidos pelo usuário são validados e sanitizados antes do uso.
• Prevenção de injeção de CQL — entrada do usuário interpolada em consultas CQL é escapada.
• Codificação de caminho de URL — todos os segmentos de caminho dinâmicos são codificados com encodeURIComponent.
• Tempos limite de solicitação — todas as solicitações HTTP têm um tempo limite de 30 segundos para evitar travamentos.
• Sanitização de erros — respostas de erro da API são truncadas e removidas de HTML antes de serem exibidas.
• Limites de paginação — limites de consulta são limitados a um máximo seguro (100) para evitar abuso.

Contribuindo

Consulte CONTRIBUTING.md para diretrizes sobre como contribuir com este projeto.

Política de Segurança

Para políticas de segurança e relatórios de vulnerabilidades, consulte SECURITY.md.

Registro de Alterações

Consulte CHANGELOG.md para um histórico de alterações.

Licença

MIT

Agradecimentos

• Model Context Protocol
• Atlassian Confluence REST API