Servidor MCP de Confluence

Servidor del Protocolo de Contexto de Modelos (MCP) para la integración de Atlassian Confluence con Claude Code.

Características

• 🔍 Buscar en páginas de Confluence usando CQL (Confluence Query Language)

• 📄 Leer páginas por ID o título

• ✏️ Crear y actualizar páginas

• 🏷️ Gestionar etiquetas y metadatos

• 📁 Listar espacios y archivos adjuntos

• 🔐 Seguridad mediante autenticación básica con tokens de API

Related MCP server: mcp-confluence

Instalación

Requisitos previos

• Node.js 18+ y npm

• Cuenta de Atlassian Confluence Cloud

• Token de API (ver Configuración más abajo)

Configuración inicial

git clone https://github.com/gkrauchunas-arlo/confluence-mcp.git
cd confluence-mcp
npm install

Configuración

1. Copia .env.example a .env:

   cp .env.example .env

2. Rellena tus credenciales de Atlassian en .env:

   ATLASSIAN_SITE=your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-token

Cómo obtener un token de API:

1. Ve a https://id.atlassian.com/manage-profile/security/api-tokens

2. Haz clic en "Create API token"

3. Dale un nombre (p. ej., "Claude Code MCP") y copia el token en .env

Pruebas

# Test Confluence API connectivity
node test-confluence.js

# Test MCP protocol (via stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Conexión con Claude Code

Opción 1: CLI (Recomendado)

claude mcp add --transport stdio confluence \
  --env ATLASSIAN_SITE="your-domain.atlassian.net" \
  --env ATLASSIAN_EMAIL="your-email@example.com" \
  --env ATLASSIAN_API_TOKEN="your-token" \
  -- node /absolute/path/to/confluence-mcp/index.js

Reemplaza /absolute/path/to/ con tu ruta de instalación real (p. ej., /home/username/confluence-mcp).

Opción 2: Archivo de configuración

Añade esto a tu archivo de configuración MCP de Claude Code:

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/absolute/path/to/confluence-mcp/index.js"],
      "env": {
        "ATLASSIAN_SITE": "your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-token"
      }
    }
  }
}

Ubicaciones del archivo de configuración:

• Linux: ~/.config/claude-code/mcp_servers.json o ~/.claude/config/mcp_servers.json

• macOS: ~/Library/Application Support/claude-code/mcp_servers.json

• Windows: %APPDATA%\claude-code\mcp_servers.json

Después de la configuración, reinicia Claude Code para activar el servidor MCP.

Herramientas disponibles

Búsqueda y navegación

• confluence_search - Búsqueda CQL en todo el contenido

  • Parámetros: query (cadena), limit (número, opcional), spaceKey (cadena, opcional)

  • Ejemplo: Buscar páginas con "API" en el título dentro de un espacio específico

• confluence_list_spaces - Listar todos los espacios

  • Parámetros: limit (número, opcional, por defecto: 25)

  • Devuelve: Lista de todos los espacios de Confluence accesibles para tu cuenta

Leer contenido

• confluence_get_page - Obtener página por ID

  • Parámetros: pageId (cadena)

  • Devuelve: Datos completos de la página, incluyendo contenido, versión y metadatos

• confluence_get_page_by_title - Buscar página por título y espacio

  • Parámetros: title (cadena), spaceKey (cadena)

  • Devuelve: Página que coincide exactamente con el título en el espacio especificado

• confluence_get_space - Obtener información del espacio

  • Parámetros: spaceKey (cadena)

  • Devuelve: Metadatos y configuración del espacio

• confluence_get_attachments - Listar archivos adjuntos de una página

  • Parámetros: pageId (cadena)

  • Devuelve: Lista de todos los archivos adjuntos en una página

Crear y editar

• confluence_create_page - Crear una nueva página

  • Parámetros: title (cadena), spaceKey (cadena), content (cadena HTML), parentId (cadena, opcional)

  • Crea una nueva página en el espacio especificado, opcionalmente como hija de otra página

• confluence_update_page - Actualizar una página existente

  • Parámetros: pageId (cadena), title (cadena), content (cadena HTML), version (número)

  • Actualiza una página con nuevo contenido. El número de versión debe coincidir con la versión actual de la página.

Metadatos

• confluence_add_labels - Añadir etiquetas a una página

  • Parámetros: pageId (cadena), labels (matriz de cadenas)

  • Añade una o más etiquetas a una página para su categorización

Ejemplos de uso

Una vez conectado a Claude Code, puedes usar lenguaje natural para interactuar con Confluence:

Buscar páginas

Find all pages about "API documentation" in Confluence

Leer una página

Read the contents of Confluence page with ID 12345

Crear una nueva página

Create a new page in the DEV space titled "API Guidelines" with this content:
<h1>API Guidelines</h1>
<p>This document describes our API design principles.</p>

Actualizar una página

Update Confluence page 12345 to add a new section about authentication

Añadir etiquetas

Add labels "documentation" and "api" to Confluence page 12345

Ejemplos de consultas CQL

La herramienta confluence_search admite Confluence Query Language (CQL):

type=page AND title~"API"
type=page AND space=DEV
type=page ORDER BY lastmodified DESC
type=page AND label=documentation
type=page AND creator=currentUser()

Referencia de la API

Este servidor MCP utiliza la API REST de Confluence:

• URL base: https://{site}.atlassian.net/wiki/rest/api

• Autenticación: Autenticación básica con correo electrónico + token de API

• Versión de la API: Cloud REST API (estable)

• Documentación completa de la API

Solución de problemas

"Authentication failed"

• Verifica tu correo electrónico y token de API en .env

• Asegúrate de que el token no haya caducado (los tokens de API no caducan, pero pueden ser revocados)

• Comprueba que estás usando un token de API, no la contraseña de tu cuenta de Atlassian

"MCP tools not showing up"

• Reinicia Claude Code completamente (cierra y vuelve a abrir)

• Comprueba los registros del servidor en busca de errores ejecutando node index.js directamente

• Verifica la configuración con claude mcp list

• Asegúrate de que se utilice la ruta absoluta completa en la configuración

Errores de "Permission denied"

• Asegúrate de que tu cuenta de Atlassian tenga acceso a los espacios/páginas solicitados

• Algunas operaciones requieren permisos específicos (p. ej., administrador de espacio para crear páginas)

• Comprueba los permisos de espacio en la interfaz web de Confluence

"Page version conflict"

• Al actualizar una página, debes proporcionar el número de versión actual

• Obtén la versión actual primero con confluence_get_page

• El servidor incrementará automáticamente la versión en 1

Formato de contenido

Las páginas de Confluence utilizan el Formato de almacenamiento (HTML con macros de Confluence). Para páginas simples, el HTML estándar funciona:

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Bullet point 1</li>
  <li>Bullet point 2</li>
</ul>
<pre><code>Code block</code></pre>

Para funciones avanzadas, consulta la documentación del formato de almacenamiento de Confluence.

Arquitectura

Construido sobre:

• @modelcontextprotocol/sdk - Implementación del protocolo MCP

• axios - Cliente HTTP para la API REST de Confluence

• dotenv - Gestión de configuración

El servidor se ejecuta como un servidor MCP basado en stdio, comunicándose con Claude Code a través de JSON-RPC 2.0 sobre entrada/salida estándar.

Desarrollo

Estructura del proyecto

confluence-mcp/
├── index.js              # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── test-confluence.js    # Confluence API connectivity tests
├── test-mcp.js           # MCP protocol tests (WIP)
├── .env.example          # Example configuration
├── .env                  # Your configuration (gitignored)
└── README.md             # This file

Ejecución de pruebas

# Test Confluence API directly
node test-confluence.js

# Test MCP server via stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Contribución

¡Las contribuciones son bienvenidas! Por favor:

1. Haz un fork del repositorio

2. Crea una rama de características (git checkout -b feature/amazing-feature)

3. Realiza tus cambios con pruebas

4. Confirma tus cambios (git commit -m 'feat: add amazing feature')

5. Envía la rama (git push origin feature/amazing-feature)

6. Abre una Pull Request

Limitaciones conocidas

1. Carga de archivos adjuntos - Aún no implementada (requiere codificación multipart/form-data)

2. Formato de texto enriquecido - Solo se admite HTML básico, las macros de Confluence pueden ser complejas

3. Paginación - Los conjuntos de resultados grandes están limitados por el parámetro limit

4. Permisos - La API solo devuelve contenido accesible para el usuario autenticado

Licencia

ISC

Reconocimientos

• Arquitectura inspirada en rovo-mcp

• Creado para Claude Code

• Utiliza el Protocolo de Contexto de Modelos

Soporte

• Problemas: https://github.com/gkrauchunas-arlo/confluence-mcp/issues

• Documentación de la API de Atlassian: https://developer.atlassian.com/cloud/confluence/rest/

• Especificación MCP: https://modelcontextprotocol.io/specification

Creado por: gkrauchunas-arlo Estado: Estable v1.0.0 - Todas las funciones principales implementadas y probadas