MCP-Atlassian: Descripción Detallada del Proyecto

Resumen del Proyecto

MCP-Atlassian es un servidor basado en el Protocolo de Contexto de Modelo (MCP) diseñado específicamente para productos de Atlassian (Confluence y Jira). Este proyecto permite que asistentes de IA (como Claude) accedan y operen directamente con los datos de su espacio de trabajo de Atlassian, implementando una gestión de flujo de trabajo inteligente.

Información Básica del Proyecto

• Nombre del Proyecto: mcp-atlassian
• Desarrollador: sooperset
• Dirección de GitHub: https://github.com/sooperset/mcp-atlassian
• Método de Despliegue: Contenedor Docker

Características y Funcionalidades Principales

Operaciones Inteligentes Impulsadas por IA

El proyecto soporta diversas operaciones inteligentes impulsadas por asistentes de IA:

• 📝 Actualización Automática de Jira - "Actualiza Jira con las notas de nuestra reunión"
• 🔍 Búsqueda en Confluence Impulsada por IA - "Encuentra nuestra guía de OKR en Confluence y resúmela"
• 🐛 Filtrado Inteligente de Incidencias de Jira - "Muestra los bugs urgentes del proyecto PROJ de la semana pasada"
• 📄 Creación y Gestión de Contenido - "Crea un documento de diseño técnico para la función XYZ"

Soporte de Compatibilidad de Productos

Producto	Tipo de Despliegue	Estado de Soporte
Confluence	Cloud	✅ Totalmente Compatible
Confluence	Server/Data Center	✅ Compatible (Versión 6.0+)
Jira	Cloud	✅ Totalmente Compatible
Jira	Server/Data Center	✅ Compatible (Versión 8.14+)

Instalación y Configuración

Requisitos Previos

• Entorno Docker
• Token de API de Atlassian (versión Cloud) o Token de Acceso Personal (versión Server)

Obtención de Tokens de Autenticación

Atlassian Cloud:

1. Visite https://id.atlassian.com/manage-profile/security/api-tokens
2. Haga clic en "Create API token", nombre y copie el token

Server/Data Center:

1. Vaya a Perfil → Tokens de Acceso Personal
2. Haga clic en "Create token", establezca la fecha de caducidad y copie el token

Obtención de la Imagen Docker

# Descargar la imagen precompilada
docker pull ghcr.io/sooperset/mcp-atlassian:latest

Configuración de Integración con IDE

Configuración de Claude Desktop

Ubicación del archivo de configuración:

• 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: Pasar Variables Directamente

{
  "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: Usar un Archivo de Entorno

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

Configuración para 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"
      }
    }
  }
}

Descripción de las Variables de Entorno

Variables de entorno comunes:

• CONFLUENCE_SPACES_FILTER: Filtrar por clave de espacio (ejemplo: "DEV,TEAM,DOC")
• JIRA_PROJECTS_FILTER: Filtrar por clave de proyecto (ejemplo: "PROJ,DEV,SUPPORT")
• READ_ONLY_MODE: Establecer en "true" para deshabilitar las operaciones de escritura
• MCP_VERBOSE: Establecer en "true" para habilitar el registro detallado
• ENABLED_TOOLS: Lista de nombres de herramientas separados por comas

Funcionalidades de Herramientas Disponibles

Herramientas de Confluence

Nombre de la Herramienta	Descripción de la Funcionalidad
confluence_search	Buscar contenido de Confluence usando CQL
confluence_get_page	Obtener el contenido de una página específica
confluence_get_page_children	Obtener las subpáginas de una página
confluence_get_page_ancestors	Obtener las páginas padre de una página
confluence_get_comments	Obtener los comentarios de una página
confluence_create_page	Crear una nueva página
confluence_update_page	Actualizar una página existente
confluence_delete_page	Eliminar una página
confluence_get_labels	Obtener las etiquetas
confluence_add_label	Agregar una etiqueta

Herramientas de Jira

Nombre de la Herramienta	Descripción de la Funcionalidad
jira_get_issue	Obtener los detalles de una incidencia específica
jira_search	Buscar incidencias usando JQL
jira_get_project_issues	Obtener las incidencias de un proyecto
jira_get_epic_issues	Obtener las incidencias de una épica
jira_create_issue	Crear una nueva incidencia
jira_batch_create_issues	Crear incidencias en lote
jira_update_issue	Actualizar una incidencia existente
jira_delete_issue	Eliminar una incidencia
jira_get_transitions	Obtener las transiciones de estado de una incidencia
jira_transition_issue	Transicionar el estado de una incidencia
jira_add_comment	Agregar un comentario
jira_add_worklog	Agregar un registro de trabajo
jira_get_worklog	Obtener el registro de trabajo
jira_download_attachments	Descargar adjuntos
jira_link_to_epic	Enlazar a una épica
jira_get_agile_boards	Obtener los tableros Kanban
jira_get_board_issues	Obtener las incidencias de un tablero Kanban
jira_get_sprints_from_board	Obtener los sprints de un tablero Kanban
jira_get_sprint_issues	Obtener las incidencias de un sprint
jira_create_sprint	Crear un sprint
jira_update_sprint	Actualizar un sprint
jira_get_issue_link_types	Obtener los tipos de enlace de incidencias
jira_create_issue_link	Crear un enlace de incidencia
jira_remove_issue_link	Eliminar un enlace de incidencia

Nota: Las herramientas marcadas con * solo están disponibles en Jira Cloud

Control de Acceso

Filtrado de Herramientas

Utilice el flag --enabled-tools o la variable de entorno ENABLED_TOOLS para especificar las herramientas disponibles:

# A través de la variable de entorno
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# O a través del flag de línea de comandos
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

Control de Lectura/Escritura

Las herramientas se dividen en operaciones de lectura y escritura. Cuando READ_ONLY_MODE está habilitado, solo las operaciones de lectura están disponibles, independientemente de la configuración de ENABLED_TOOLS.

Resolución de Problemas

Solución de Problemas Comunes

Fallo de Autenticación:

• Versión Cloud: Verifique el token de API (no la contraseña de la cuenta)
• Versión Server/Data Center: Verifique que el token de acceso personal sea válido y no haya caducado
• Servidores Confluence antiguos: Puede que necesite usar CONFLUENCE_USERNAME y CONFLUENCE_API_TOKEN (el token es la contraseña)

Problemas con el Certificado SSL: Si encuentra errores SSL en implementaciones Server/Data Center, establezca CONFLUENCE_SSL_VERIFY=false o JIRA_SSL_VERIFY=false

Errores de Permisos: Asegúrese de que la cuenta de Atlassian tenga permisos suficientes para acceder a los espacios/proyectos relevantes

Métodos de Depuración

Usar MCP Inspector para Probar:

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

Ver los Logs:

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

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

Usando la Transmisión SSE

Además de la transmisión stdio estándar, también se admiten los eventos enviados por el servidor (SSE):

1. Inicie el servidor manualmente en la 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 el IDE para conectarse al servidor en ejecución:

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

Consideraciones de Seguridad

• Nunca comparta los tokens de API
• Mantenga los archivos .env seguros y privados
• Consulte SECURITY.md para conocer las mejores prácticas

Arquitectura Técnica

Este proyecto utiliza una implementación en contenedores Docker, comunicándose con asistentes de IA a través del Protocolo de Contexto de Modelo. Admite múltiples métodos de transmisión (stdio y SSE), lo que permite una adaptación flexible a diferentes entornos de implementación y escenarios de uso.

El diseño del proyecto considera las necesidades de las aplicaciones empresariales, admitiendo las versiones en la nube y las implementaciones privadas de Atlassian, proporcionando autenticación completa, control de permisos y mecanismos de seguridad.

---

Nota: Este no es un producto oficial de Atlassian, sino un proyecto de código abierto mantenido por el desarrollador de la comunidad sooperset.