Atlassian Confluence

Interactúa con espacios, páginas y contenido de Atlassian Confluence Cloud en tiempo real.

GitHub
60

Documentación

Conecta IA a tu base de conocimiento de Confluence

Transforma la forma en que accedes e interactúas con el conocimiento de tu equipo conectando Claude, Cursor AI y otros asistentes de IA directamente a tus espacios, páginas y documentación de Confluence. Obtén respuestas instantáneas desde tu base de conocimiento, busca en todos tus espacios y agiliza tu flujo de trabajo de documentación.

NPM Version

Lo que puedes hacer

  • Pregunta a la IA sobre tu documentación: "¿Cuál es nuestro proceso de autenticación de API?"
  • Busca en todos los espacios: "Encuentra todas las páginas sobre mejores prácticas de seguridad"
  • Obtén respuestas instantáneas: "Muéstrame las últimas notas de versión del espacio Product"
  • Accede al conocimiento del equipo: "¿Cuáles son nuestras políticas de RRHH para trabajo remoto?"
  • Revisa comentarios de páginas: "Muéstrame la discusión sobre el documento de arquitectura"
  • Crea y actualiza contenido: "Crea una nueva página en el espacio DEV"

Perfecto para

  • Desarrolladores que necesitan acceso rápido a documentación técnica y guías de API
  • Gerentes de Producto que buscan requisitos, especificaciones y actualizaciones de proyectos
  • Equipos de RRHH que acceden rápidamente a documentos de políticas y recursos para empleados
  • Equipos de Soporte que encuentran guías de solución de problemas y artículos de la base de conocimiento
  • Cualquier persona que quiera interactuar con Confluence usando lenguaje natural

Inicio rápido

Ponte en marcha en 2 minutos:

1. Obtén tus credenciales de Confluence

Genera un token de API de Confluence:

  1. Ve a Tokens de API de Atlassian
  2. Haz clic en Crear token de API
  3. Dale un nombre como "Asistente de IA"
  4. Copia el token generado inmediatamente (¡no lo volverás a ver!)

2. Pruébalo al instante

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Confluence spaces (TOON format by default)
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# Get details about a specific space with field filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces/123456" \
  --jq "{id: id, key: key, name: name, type: type}"

# Get a page with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/789" \
  --jq "{id: id, title: title, status: status}"

# Search for pages (using CQL)
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND space=DEV"}'

Conéctate a asistentes de IA

Para usuarios de Claude Desktop

Añade esto a tu archivo de configuración de Claude (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "confluence": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-confluence"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Reinicia Claude Desktop y verás el servidor de confluence en la barra de estado.

Para otros asistentes de IA

La mayoría de los asistentes de IA admiten MCP (Cursor AI, Continue.dev y otros). Instala el servidor globalmente:

npm install -g @aashari/mcp-server-atlassian-confluence

Luego configura tu asistente de IA para usar el servidor MCP con transporte STDIO. El binario está disponible como mcp-atlassian-confluence después de la instalación global.

Alternativa: Archivo de configuración

Crea ~/.mcp/configs.json para configuración a nivel de sistema:

{
  "confluence": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

Claves de configuración alternativas: El sistema también acepta "atlassian-confluence", "@aashari/mcp-server-atlassian-confluence" o "mcp-server-atlassian-confluence" en lugar de "confluence".

Uso de variables de entorno

También puedes configurar las credenciales usando variables de entorno o un archivo .env:

# Create a .env file in your project directory
cat > .env << EOF
ATLASSIAN_SITE_NAME=your-company
ATLASSIAN_USER_EMAIL=your.email@company.com
ATLASSIAN_API_TOKEN=your_api_token
DEBUG=false
EOF

El servidor cargará automáticamente estos valores desde:

  1. Variables de entorno
  2. Archivo .env en el directorio actual
  3. ~/.mcp/configs.json (como se muestra arriba)

Herramientas disponibles

Este servidor MCP proporciona 5 herramientas genéricas que pueden acceder a cualquier endpoint de la API de Confluence:

HerramientaDescripción
conf_getGET a cualquier endpoint de la API de Confluence (leer datos)
conf_postPOST a cualquier endpoint (crear recursos)
conf_putPUT a cualquier endpoint (reemplazar recursos)
conf_patchPATCH a cualquier endpoint (actualizaciones parciales)
conf_deleteDELETE desde cualquier endpoint (eliminar recursos)

Parámetros de las herramientas

Todas las herramientas comparten estos parámetros comunes:

  • path (obligatorio): La ruta del endpoint de la API (p. ej., /wiki/api/v2/spaces)
  • queryParams (opcional): Parámetros de consulta como pares clave-valor (p. ej., {"limit": "25", "space-id": "123"})
  • jq (opcional): Expresión JMESPath para filtrar/transformar la respuesta (p. ej., results[*].{id: id, title: title})
  • outputFormat (opcional): Formato de salida: "toon" (predeterminado, 30-60% menos tokens) o "json"

Herramientas que aceptan un cuerpo de solicitud (conf_post, conf_put, conf_patch):

  • body (obligatorio): Cuerpo de la solicitud como objeto JSON

Rutas de API comunes

Espacios:

  • /wiki/api/v2/spaces - Listar todos los espacios
  • /wiki/api/v2/spaces/{id} - Obtener detalles del espacio

Páginas:

  • /wiki/api/v2/pages - Listar páginas (usa el parámetro de consulta space-id para filtrar)
  • /wiki/api/v2/pages/{id} - Obtener detalles de la página
  • /wiki/api/v2/pages/{id}/body - Obtener el cuerpo de la página (usa el parámetro body-format)
  • /wiki/api/v2/pages/{id}/children - Obtener páginas hijas
  • /wiki/api/v2/pages/{id}/labels - Obtener etiquetas de la página

Comentarios:

  • /wiki/api/v2/pages/{id}/footer-comments - Listar/añadir comentarios de pie de página
  • /wiki/api/v2/pages/{id}/inline-comments - Listar/añadir comentarios en línea
  • /wiki/api/v2/footer-comments/{comment-id} - Obtener/actualizar/eliminar comentario

Publicaciones de blog:

  • /wiki/api/v2/blogposts - Listar publicaciones de blog
  • /wiki/api/v2/blogposts/{id} - Obtener publicación de blog

Búsqueda:

  • /wiki/rest/api/search - Buscar contenido (usa el parámetro de consulta cql)

Formato de salida TOON

¿Qué es TOON? TOON (Token-Oriented Object Notation) es un formato optimizado para la eficiencia de tokens de LLM, que reduce los costos de tokens en un 30-60% en comparación con JSON. Es el formato de salida predeterminado para todas las herramientas.

Beneficios:

  • Los arreglos tabulares usan menos tokens que los arreglos JSON
  • Sintaxis mínima (sin comillas, corchetes o comas innecesarios)
  • Sigue siendo legible para humanos y analizable

Cuándo usar JSON en su lugar:

  • Cuando necesitas JSON estándar para otras herramientas
  • Cuando se necesita depuración o inspección manual

Comparación de ejemplo:

// JSON format (verbose)
{"results": [{"id": "123", "title": "My Page"}, {"id": "456", "title": "Other Page"}]}

// TOON format (efficient)
results:
  - id: 123
    title: My Page
  - id: 456
    title: Other Page

Para usar JSON en lugar de TOON, establece outputFormat: "json" en tu solicitud.

Filtrado JMESPath

Todas las herramientas admiten filtrado opcional con JMESPath (jq) para extraer datos específicos y reducir costos de tokens:

# Get just space names and keys
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --jq "results[].{id: id, key: key, name: name}"

# Get page title and status
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages/123456" \
  --jq "{id: id, title: title, status: status}"

IMPORTANTE: Usa siempre el parámetro jq para filtrar las respuestas a solo los campos que necesitas. Las respuestas sin filtrar pueden ser muy grandes y costosas en términos de tokens.

Referencia de sintaxis JMESPath:

  • Documentación oficial: jmespath.org
  • Patrones comunes:
    • results[*] - Todos los elementos en el arreglo de resultados
    • results[0] - Solo el primer elemento
    • results[*].id - Solo los IDs de todos los elementos
    • results[*].{id: id, title: title} - Crear objetos con campos seleccionados
    • results[?status=='current'] - Filtrar por condición

Ejemplos del mundo real

Explora tu base de conocimiento

Pregunta a tu asistente de IA:

  • "Lista todos los espacios en nuestro Confluence"
  • "Muéstrame detalles sobre el espacio Engineering"
  • "¿Qué páginas hay en nuestro espacio Product?"
  • "Encuentra las páginas más recientes en el espacio Marketing"

Busca y encuentra información

Pregunta a tu asistente de IA:

  • "Busca páginas sobre autenticación de API"
  • "Encuentra toda la documentación con 'security' en el título"
  • "Muéstrame páginas etiquetadas con 'getting-started'"
  • "Busca contenido en el espacio DEV sobre implementación"

Accede a contenido específico

Pregunta a tu asistente de IA:

  • "Obtén el contenido de la página Guía de Autenticación de API"
  • "Muéstrame el documento de lista de verificación de incorporación"
  • "¿Qué hay en nuestra página de políticas de seguridad?"
  • "Muestra las últimas notas de versión"

Crea y actualiza contenido

Pregunta a tu asistente de IA:

  • "Crea una nueva página en el espacio DEV titulada 'Guía de API'"
  • "Añade un comentario al documento de arquitectura"
  • "Actualiza el contenido de la página con la nueva información de la versión"

Comandos CLI

La CLI refleja las herramientas MCP para acceso directo desde la terminal. Todos los comandos admiten los mismos parámetros que las herramientas.

Comandos disponibles

  • get - GET a cualquier endpoint de Confluence
  • post - POST a cualquier endpoint
  • put - PUT a cualquier endpoint
  • patch - PATCH a cualquier endpoint
  • delete - DELETE desde cualquier endpoint

Parámetros CLI

Todos los comandos:

  • -p, --path <path> (obligatorio) - Ruta del endpoint de la API
  • -q, --query-params <json> (opcional) - Parámetros de consulta como JSON
  • --jq <expression> (opcional) - Expresión de filtro JMESPath
  • -o, --output-format <format> (opcional) - Formato de salida: toon (predeterminado) o json

Comandos con cuerpo (post, put, patch):

  • -b, --body <json> (obligatorio) - Cuerpo de la solicitud como JSON

Ejemplos

# GET request
npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

# GET with query parameters and JMESPath filter
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/pages" \
  --query-params '{"space-id": "123456", "limit": "10"}' \
  --jq "results[*].{id: id, title: title}"

# GET with JSON output format
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --output-format json

# POST request (create a page)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages" \
  --body '{"spaceId": "123456", "status": "current", "title": "New Page", "body": {"representation": "storage", "value": "<p>Content here</p>"}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-confluence post \
  --path "/wiki/api/v2/pages/789/footer-comments" \
  --body '{"body": {"representation": "storage", "value": "<p>My comment</p>"}}'

# PUT request (update page - requires version increment)
npx -y @aashari/mcp-server-atlassian-confluence put \
  --path "/wiki/api/v2/pages/789" \
  --body '{"id": "789", "status": "current", "title": "Updated Title", "spaceId": "123456", "body": {"representation": "storage", "value": "<p>Updated content</p>"}, "version": {"number": 2}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-confluence patch \
  --path "/wiki/api/v2/spaces/123456" \
  --body '{"name": "New Space Name"}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-confluence delete \
  --path "/wiki/api/v2/pages/789"

Manejo de respuestas

Truncamiento de respuestas grandes

Cuando las respuestas de la API superan aproximadamente 40,000 caracteres (~10,000 tokens), el servidor trunca automáticamente la respuesta para mantenerse dentro de los límites de tokens. Cuando esto ocurre:

  1. Verás un aviso de truncamiento al final de la respuesta mostrando:

    • Cuánto de la respuesta original se muestra
    • El tamaño de la respuesta original
    • Orientación sobre cómo acceder a los datos completos

  2. La respuesta sin procesar completa se guarda en un archivo temporal en /tmp/mcp/ (la ruta se proporciona en el aviso de truncamiento)

  3. Mejores prácticas para evitar el truncamiento:

    • Usa siempre el parámetro jq para filtrar respuestas a solo los campos necesarios
    • Usa el parámetro de consulta limit para restringir el número de resultados (p. ej., {"limit": "5"})
    • Solicita recursos específicos por ID en lugar de listar todos
    • Usa consultas CQL específicas para búsquedas

Ejemplo de filtrado eficiente:

# Instead of getting all space data (can be huge):
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces"

# Get only the fields you need:
npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/api/v2/spaces" \
  --query-params '{"limit": "10"}' \
  --jq "results[*].{id: id, key: key, name: name}"

Registro de depuración

Habilita el registro de depuración para ver información detallada de solicitudes/respuestas:

# Set DEBUG environment variable
export DEBUG=true

# For MCP mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence

# For CLI mode
DEBUG=true npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces"

Los registros de depuración se escriben en: ~/.mcp/data/@aashari-mcp-server-atlassian-confluence.[session-id].log

Pruebas y desarrollo

Uso del Inspector MCP

El Inspector MCP proporciona una interfaz visual para probar herramientas:

# Install the server globally
npm install -g @aashari/mcp-server-atlassian-confluence

# Run with MCP Inspector
npx @modelcontextprotocol/inspector node $(which mcp-atlassian-confluence)

O usa el comando de desarrollo integrado si has clonado el repositorio:

npm run mcp:inspect

Esto inicia el servidor en modo HTTP y abre la interfaz del inspector en tu navegador.

Modo HTTP para pruebas

Puedes ejecutar el servidor en modo HTTP para probar con curl u otros clientes HTTP:

# Start server in HTTP mode
TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

El servidor escuchará en http://localhost:3000/mcp de forma predeterminada. Puedes cambiar el puerto:

PORT=8080 TRANSPORT_MODE=http npx -y @aashari/mcp-server-atlassian-confluence

Pruebas con curl:

# Initialize session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "clientInfo": {"name": "curl-test", "version": "1.0.0"}, "capabilities": {}}}'

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "conf_get", "arguments": {"path": "/wiki/api/v2/spaces", "queryParams": {"limit": "5"}}}}'

La respuesta viene como eventos enviados por el servidor (SSE) con el formato:

event: message
data: {"jsonrpc": "2.0", "id": 1, "result": {...}}

Solución de problemas

"Error de autenticación" o "403 Prohibido"

  1. Verifica los permisos de tu token de API:

  2. Verifica el formato de tu nombre de sitio:

    • Si tu URL de Confluence es https://mycompany.atlassian.net
    • Tu nombre de sitio debería ser solo mycompany

  3. Prueba tus credenciales:

    npx -y @aashari/mcp-server-atlassian-confluence get --path "/wiki/api/v2/spaces?limit=1"

"Recurso no encontrado" o "404"

  1. Verifica la ruta de la API:

    • Las rutas distinguen entre mayúsculas y minúsculas
    • Usa IDs numéricos para espacios y páginas (no claves)
    • Verifica que el recurso exista en tu navegador

  2. Verifica los permisos de acceso:

    • Asegúrate de tener acceso al espacio/página en tu navegador
    • Algún contenido puede estar restringido a ciertos usuarios

"No se encontraron resultados" al buscar

  1. Prueba diferentes términos de búsqueda:

    • Usa sintaxis CQL para búsquedas avanzadas
    • Prueba criterios de búsqueda más amplios

  2. Verifica la sintaxis CQL:

    • Valida tu CQL en la búsqueda avanzada de Confluence primero

Problemas de integración con Claude Desktop

  1. Reinicia Claude Desktop después de actualizar el archivo de configuración
  2. Verifica la ubicación del archivo de configuración:
    • macOS: ~/.claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

Obtener ayuda

Si sigues teniendo problemas:

  1. Ejecuta un comando de prueba simple para verificar que todo funciona
  2. Revisa los Problemas de GitHub para problemas similares
  3. Crea un nuevo problema con tu mensaje de error y detalles de configuración

Preguntas frecuentes

¿Qué permisos necesito?

Tu cuenta de Atlassian necesita:

  • Acceso a Confluence con los permisos adecuados para los espacios que quieras consultar
  • Token de API con permisos apropiados (se otorgan automáticamente al crear uno)

¿Puedo usar esto con Confluence Server (local)?

Actualmente, esta herramienta solo admite Confluence Cloud. El soporte para Confluence Server/Data Center puede añadirse en versiones futuras.

¿Cómo encuentro mi nombre de sitio?

Tu nombre de sitio es la primera parte de tu URL de Confluence:

  • URL: https://mycompany.atlassian.net -> Nombre de sitio: mycompany
  • URL: https://acme-corp.atlassian.net -> Nombre de sitio: acme-corp

¿Con qué asistentes de IA funciona esto?

Con cualquier asistente de IA que admita el Protocolo de Contexto de Modelo (MCP):

  • Claude Desktop
  • Cursor AI
  • Continue.dev
  • Muchos otros

¿Mis datos están seguros?

¡Sí! Esta herramienta:

  • Se ejecuta completamente en tu máquina local
  • Usa tus propias credenciales de Confluence
  • Nunca envía tus datos a terceros
  • Solo accede a lo que le des permiso de acceder

¿Puedo buscar en todos mis espacios a la vez?

¡Sí! Usa consultas CQL para búsquedas entre espacios. Por ejemplo:

npx -y @aashari/mcp-server-atlassian-confluence get \
  --path "/wiki/rest/api/search" \
  --query-params '{"cql": "type=page AND text~\"API documentation\""}'

Migración desde v2.x

La versión 3.0 reemplaza más de 8 herramientas específicas con 5 herramientas genéricas de métodos HTTP. Si estás actualizando desde v2.x:

Antes (v2.x):

conf_ls_spaces, conf_get_space, conf_ls_pages, conf_get_page,
conf_search, conf_ls_comments, conf_add_comment, ...

Después (v3.0):

conf_get, conf_post, conf_put, conf_patch, conf_delete

Ejemplos de migración:

  • conf_ls_spaces -> conf_get con la ruta /wiki/api/v2/spaces
  • conf_get_space -> conf_get con la ruta /wiki/api/v2/spaces/{id}
  • conf_ls_pages -> conf_get con la ruta /wiki/api/v2/pages?space-id={id}
  • conf_get_page -> conf_get con la ruta /wiki/api/v2/pages/{id}
  • conf_search -> conf_get con la ruta /wiki/rest/api/search?cql=...
  • conf_add_comment -> conf_post con la ruta /wiki/api/v2/pages/{id}/footer-comments

Detalles técnicos

Requisitos

  • Node.js: 18.0.0 o superior
  • MCP SDK: 1.23.0 (utiliza la API moderna registerTool)
  • Confluence: Solo Cloud (Server/Data Center no compatibles)

Arquitectura

Este servidor sigue una arquitectura de 5 capas:

  1. Capa de herramientas (src/tools/) - Definiciones de herramientas MCP con validación Zod
  2. Capa CLI (src/cli/) - CLI basada en Commander para pruebas directas
  3. Capa de controladores (src/controllers/) - Lógica de negocio, filtrado JMESPath, formato de salida
  4. Capa de servicios (src/services/) - Comunicación con la API de Confluence
  5. Capa de utilidades (src/utils/) - Utilidades compartidas (logger, configuración, formateadores, codificador TOON)

Características

  • Herramientas genéricas de métodos HTTP - Accede a cualquier endpoint de la API de Confluence
  • Formato de salida TOON - Reducción de tokens del 30-60% frente a JSON
  • Filtrado JMESPath - Extrae solo los datos necesarios
  • Truncamiento de respuestas - Manejo automático de respuestas grandes
  • Registro de respuestas sin procesar - Respuestas completas guardadas en /tmp/mcp/
  • Transporte dual - STDIO (para Claude Desktop) y HTTP (para integraciones web)
  • Registro de depuración - Registro completo para resolución de problemas

Historial de versiones

v3.2.1 (Actual)

  • Añade registro de respuestas sin procesar con truncamiento para respuestas grandes de la API
  • Mejora la compatibilidad de dependencias

v3.2.0

  • Moderniza el SDK de MCP a v1.23.0 con la API registerTool

v3.1.0

  • Añade formato de salida TOON para respuestas LLM eficientes en tokens

v3.0.0 (Cambio importante)

  • Reemplaza más de 8 herramientas específicas de dominio con 5 herramientas genéricas de métodos HTTP
  • Añade soporte de filtrado JMESPath
  • Acceso completo a la API de Confluence mediante métodos genéricos

Consulta CHANGELOG.md para el historial completo de versiones.

Soporte

¿Necesitas ayuda? Así puedes obtener asistencia:

  1. Consulta la sección de solución de problemas anterior - los problemas más comunes están cubiertos allí
  2. Visita nuestro repositorio de GitHub para documentación y ejemplos: github.com/aashari/mcp-server-atlassian-confluence
  3. Reporta problemas en GitHub Issues
  4. Inicia una discusión para solicitudes de funciones o preguntas generales

Hecho con cuidado para equipos que quieren llevar la IA a su flujo de trabajo de gestión del conocimiento.