Atlassian-mcp-server

Servidor MCP para Atlassian Cloud (Confluence y Jira) con autenticación OAuth 2.0 sin interrupciones.

GitHub
4

Documentación

Servidor MCP de Atlassian

PyPI version Python Support License: MIT Code Quality Dependency Security

Servidor MCP para Atlassian Cloud (Confluence y Jira) con autenticación OAuth 2.0 sin interrupciones. Este servidor permite a los agentes de IA ayudar a los usuarios a documentar trabajo en Confluence, gestionar incidencias de Jira y comprender el contexto del proyecto.

Características

  • Flujo OAuth 2.0 sin interrupciones: Autenticación automática basada en navegador con seguridad PKCE
  • Arquitectura modular: Clases de cliente especializadas para operaciones de Jira, Confluence y Service Desk
  • Carga selectiva de módulos: Configure qué módulos cargar mediante variables de entorno
  • Integración con Jira: Buscar, crear y actualizar incidencias; añadir comentarios; gestionar trabajo
  • Integración con Confluence: Buscar y leer contenido para comprender el contexto
  • Gestión de servicios: Acceder a tickets de soporte y solicitudes
  • Gestión automática de tokens: Maneja la renovación de tokens automáticamente
  • Permisos mínimos: Sigue el principio de privilegio mínimo con solo los alcances requeridos

Arquitectura

El servidor utiliza una arquitectura modular con clases de cliente especializadas:

  • BaseAtlassianClient: Autenticación OAuth 2.0 central y manejo de solicitudes HTTP
  • JiraClient: Operaciones específicas de Jira (incidencias, proyectos, comentarios)
  • ConfluenceClient: Operaciones específicas de Confluence (páginas, espacios, búsqueda)
  • ServiceDeskClient: Operaciones de gestión de servicios (solicitudes, aprobaciones, CMDB de activos)

Cada módulo puede habilitarse/deshabilitarse de forma independiente para un rendimiento y seguridad óptimos.

Casos de uso

Este servidor MCP está diseñado para ayudar a los agentes de IA a asistir a los usuarios con:

  • Documentación de trabajo: Ayudar a documentar el progreso del trabajo y las decisiones en Confluence
  • Gestión de incidencias: Crear, actualizar y realizar seguimiento de incidencias de Jira basadas en conversaciones
  • Comprensión del contexto: Leer páginas de Confluence para entender los antecedentes del proyecto
  • Registro de tiempo y actividad: Realizar seguimiento de las actividades de trabajo y el tiempo dedicado a las tareas
  • Solicitudes de servicio: Acceder a tickets de gestión de servicios para contexto de soporte
  • Coordinación de proyectos: Buscar en Jira y Confluence información del proyecto

Configuración de la aplicación OAuth

1. Crear aplicación OAuth

  1. Vaya a la Consola de desarrolladores de Atlassian
  2. Haga clic en Crear → Integración OAuth 2.0
  3. Ingrese el nombre de su aplicación y acepte los términos
  4. Establezca la URL de devolución de llamada a: http://localhost:8080/callback

2. Configurar los alcances requeridos

IMPORTANTE: Debe agregar estos alcances exactos a su aplicación OAuth antes de que el servidor MCP pueda funcionar correctamente.

Alcances de la API de Jira

Navegue a Permisos → API de Jira y agregue:

  • read:jira-work - Leer incidencias, proyectos y búsquedas
  • read:jira-user - Leer información del usuario
  • write:jira-work - Crear y actualizar incidencias

Alcances de la API de Confluence

Navegue a Permisos → API de Confluence y agregue:

  • read:page:confluence - Leer contenido de páginas (alcance granular para API v2)
  • read:space:confluence - Leer información de espacios (alcance granular para API v2)
  • write:page:confluence - Crear y actualizar páginas (alcance granular para API v2)

Alcances de la API de Gestión de Servicios

Navegue a Permisos → API de Gestión de Servicios de Jira y agregue:

  • read:servicedesk-request - Leer solicitudes de gestión de servicios
  • write:servicedesk-request - Crear y actualizar solicitudes de gestión de servicios
  • manage:servicedesk-customer - Gestionar clientes y participantes del service desk
  • read:knowledgebase:jira-service-management - Buscar artículos de la base de conocimientos

Alcances de la API de Identidad de Usuario

Navegue a Permisos → API de identidad de usuario y agregue:

  • read:me - Información del perfil de usuario

Alcances principales

Estos suelen estar disponibles por defecto:

  • offline_access - Capacidad de renovación de tokens

3. Instalar la aplicación en su sitio de Atlassian

Después de configurar los alcances, debe instalar la aplicación en su sitio de Atlassian:

  1. En su aplicación OAuth, vaya a la pestaña Autorización
  2. Use el generador de URL de autorización para crear una URL de instalación:
    • Seleccione sus alcances configurados
    • Elija su sitio de Atlassian en el menú desplegable
    • Haga clic en Generar URL
  3. Visite la URL generada en su navegador para instalar la aplicación en su sitio
  4. Conceda permisos cuando Atlassian se lo solicite

Nota: Este paso es necesario antes de que el servidor MCP pueda acceder a sus datos de Atlassian. La aplicación debe estar instalada y autorizada para su sitio específico.

4. Obtener sus credenciales

Después de instalar la aplicación:

  1. Vaya a la pestaña Configuración en su aplicación OAuth
  2. Copie su ID de cliente y Secreto de cliente
  3. Establezca las variables de entorno (consulte la sección de Configuración a continuación)

5. Resumen de configuración de alcances

Mínimo requerido (12 alcances):

read:jira-work
read:jira-user  
write:jira-work
read:page:confluence
read:space:confluence
write:page:confluence
read:servicedesk-request
write:servicedesk-request
manage:servicedesk-customer
read:knowledgebase:jira-service-management
read:me
offline_access

Opcional (agregue solo si es necesario):

write:servicedesk-request      # Only if creating service tickets
manage:* scopes                # Only for administrative operations

6. Solución de problemas de alcances

Si recibe errores relacionados con alcances:

  • "el alcance no coincide": El alcance no está agregado a su aplicación OAuth en la Consola de desarrolladores
  • "usuario actual no permitido": El usuario carece de permisos a nivel de producto (contacte a su administrador de Atlassian)
  • "No autorizado": Verifique que todos los alcances requeridos estén configurados correctamente

Nota: Después de agregar nuevos alcances a su aplicación OAuth, debe volver a autenticarse usando la herramienta authenticate_atlassian para obtener tokens nuevos con los nuevos permisos.

Instalación

Requisitos previos

  • Python 3.8 o superior
  • Gestor de paquetes pip3
  • Acceso a un sitio de Atlassian Cloud
  • Aplicación OAuth configurada (consulte la Configuración de la aplicación OAuth arriba)

Instalar desde PyPI (Recomendado)

pip3 install atlassian-mcp-server

Instalar desde el repositorio de GitHub

# Install directly from GitHub repository
pip3 install git+https://github.com/rorymcmahon/atlassian-mcp-server.git

Instalar desde el código fuente

# Clone the repository
git clone https://github.com/rorymcmahon/atlassian-mcp-server.git
cd atlassian-mcp-server

# Install in development mode
pip3 install -e .

Verificar la instalación

# Check that the command is available
atlassian-mcp-server --help

# Or check the Python module
python -m atlassian_mcp_server --help

Configuración

Establezca las siguientes variables de entorno:

export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_CLIENT_ID="your-oauth-client-id"
export ATLASSIAN_CLIENT_SECRET="your-oauth-client-secret"

Configuración opcional

Selección de módulos: Controle qué módulos se cargan (por defecto: todos los módulos habilitados):

export ATLASSIAN_MODULES="jira,confluence,service_desk"  # Enable specific modules
export ATLASSIAN_MODULES="jira,confluence"              # Enable only Jira and Confluence
export ATLASSIAN_MODULES="jira"                         # Enable only Jira

Módulos disponibles:

  • jira - Gestión de incidencias de Jira y operaciones de proyectos
  • confluence - Operaciones de páginas y espacios de Confluence
  • service_desk - Gestión de servicios y operaciones de CMDB de activos

Nota: Deshabilitar módulos no utilizados reduce el uso de memoria y mejora el tiempo de inicio.

Uso

# Start the MCP server
python -m atlassian_mcp_server

# Or run directly
python src/atlassian_mcp_server/server.py

Configuración del cliente MCP

Nota: Todos los ejemplos de configuración a continuación muestran las variables de entorno requeridas. Opcionalmente, puede agregar "ATLASSIAN_MODULES": "jira,confluence,service_desk" a cualquier sección de env para controlar qué módulos se cargan.

Claude Desktop

Agregue a su archivo de configuración de Claude Desktop:

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

{
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Amazon Q Developer CLI

Cree un archivo de configuración de agente:

Archivo: ~/.aws/amazonq/cli-agents/atlassian.json

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "atlassian",
  "description": "Atlassian Jira and Confluence integration agent",
  "prompt": "You are an AI assistant with access to Atlassian Jira and Confluence. Help users manage issues, search content, and document their work.",
  "mcpServers": {
    "atlassian-mcp-server": {
      "command": "atlassian-mcp-server",
      "args": [],
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      },
      "autoApprove": ["*"],
      "disabled": false,
      "timeout": 60000,
      "initTimeout": 120000
    }
  },
  "tools": [
    "@atlassian-mcp-server/*"
  ],
  "allowedTools": [
    "@atlassian-mcp-server/*"
  ]
}

Luego use: q chat --agent atlassian

VS Code con Continue

Agregue a su configuración de Continue:

Archivo: ~/.continue/config.json

{
  "models": [...],
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

VS Code con GitHub Copilot Chat

Para GitHub Copilot Chat con soporte MCP, agregue a la configuración del espacio de trabajo:

Archivo: .vscode/settings.json

{
  "github.copilot.chat.mcp.servers": {
    "atlassian": {
      "command": "atlassian-mcp-server",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
        "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Cline (Extensión de VS Code)

Agregue a la configuración MCP de Cline:

Archivo: ~/.cline/mcp_servers.json

{
  "atlassian": {
    "command": "atlassian-mcp-server",
    "env": {
      "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
      "ATLASSIAN_CLIENT_ID": "your-oauth-client-id",
      "ATLASSIAN_CLIENT_SECRET": "your-oauth-client-secret"
    }
  }
}

Configuración de variables de entorno

Por seguridad, establezca variables de entorno en lugar de codificarlas en los archivos de configuración:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_CLIENT_ID="your-oauth-client-id"
export ATLASSIAN_CLIENT_SECRET="your-oauth-client-secret"

Luego use en las configuraciones:

{
  "env": {
    "ATLASSIAN_SITE_URL": "${ATLASSIAN_SITE_URL}",
    "ATLASSIAN_CLIENT_ID": "${ATLASSIAN_CLIENT_ID}",
    "ATLASSIAN_CLIENT_SECRET": "${ATLASSIAN_CLIENT_SECRET}"
  }
}

Flujo de autenticación

  1. Inicie el servidor MCP
  2. Use la herramienta authenticate_atlassian para comenzar el flujo OAuth
  3. El navegador se abre automáticamente al inicio de sesión de Atlassian
  4. Después de la autorización, la autenticación se completa automáticamente
  5. Las credenciales se guardan localmente para uso futuro

Herramientas disponibles

Autenticación

  • authenticate_atlassian() - Iniciar flujo de autenticación OAuth sin interrupciones

Operaciones de Jira

  • jira_search(jql, max_results=50) - Buscar incidencias con JQL
  • jira_get_issue(issue_key) - Obtener detalles de incidencia específica
  • jira_create_issue(project_key, summary, description, issue_type="Task") - Crear nueva incidencia
  • jira_update_issue(issue_key, summary=None, description=None) - Actualizar incidencia existente
  • jira_add_comment(issue_key, comment) - Agregar comentario a una incidencia

Operaciones de Confluence

Gestión de contenido principal

  • confluence_search(query, limit=10) - Buscar contenido de Confluence
  • confluence_get_page(page_id) - Obtener contenido de página específica
  • confluence_create_page(space_key, title, content, parent_id=None) - Crear nueva página de Confluence
  • confluence_update_page(page_id, title, content, version) - Actualizar página de Confluence existente

Gestión de espacios

  • confluence_list_spaces(limit=25, space_type=None, status="current") - Listar espacios disponibles
  • confluence_get_space(space_id, include_icon=False) - Obtener información detallada del espacio
  • confluence_get_space_pages(space_id, limit=25, status="current") - Obtener páginas en un espacio

Búsqueda y descubrimiento mejorados

  • confluence_search_content(query, limit=25, space_id=None) - Búsqueda avanzada de contenido
  • confluence_get_page_children(page_id, limit=25) - Obtener páginas hijas

Comentarios y colaboración

  • confluence_get_page_comments(page_id, limit=25) - Obtener comentarios de página
  • confluence_add_comment(page_id, comment, parent_comment_id=None) - Agregar comentario a una página
  • confluence_get_comment(comment_id) - Obtener detalles de comentario específico

Etiquetas y organización

  • confluence_get_page_labels(page_id, limit=25) - Obtener etiquetas de una página
  • confluence_search_by_label(label_id, limit=25) - Encontrar páginas con etiqueta específica
  • confluence_list_labels(limit=25, prefix=None) - Listar todas las etiquetas disponibles

Archivos adjuntos

  • confluence_get_page_attachments(page_id, limit=25) - Obtener archivos adjuntos de página
  • confluence_get_attachment(attachment_id) - Obtener detalles de archivo adjunto

Historial de versiones

  • confluence_get_page_versions(page_id, limit=25) - Obtener historial de versiones de página
  • confluence_get_page_version(page_id, version_number) - Obtener versión específica de página

Operaciones de gestión de servicios

Herramientas de descubrimiento (esenciales para agentes de IA)

  • servicedesk_check_availability() - Verificar si Jira Service Management está configurado
  • servicedesk_list_service_desks(limit=50) - Listar service desks disponibles para crear solicitudes
  • servicedesk_get_service_desk(service_desk_id) - Obtener información detallada del service desk
  • servicedesk_list_request_types(service_desk_id=None, limit=50) - Listar tipos de solicitud disponibles
  • servicedesk_get_request_type(service_desk_id, request_type_id) - Obtener información detallada del tipo de solicitud
  • servicedesk_get_request_type_fields(service_desk_id, request_type_id) - Obtener campos obligatorios/opcionales para el tipo de solicitud

Gestión de solicitudes

  • servicedesk_get_requests(service_desk_id=None, limit=50) - Obtener solicitudes del service desk
  • servicedesk_get_request(issue_key) - Obtener detalles de solicitud específica del service desk
  • servicedesk_create_request(service_desk_id, request_type_id, summary, description) - Crear nueva solicitud de servicio
  • servicedesk_add_comment(issue_key, comment, public=True) - Agregar comentario a una solicitud de servicio
  • servicedesk_get_request_comments(issue_key, limit=50) - Obtener comentarios de una solicitud de servicio
  • servicedesk_get_request_status(issue_key) - Obtener estado de la solicitud de servicio
  • servicedesk_get_request_transitions(issue_key) - Obtener transiciones de estado disponibles para la solicitud
  • servicedesk_transition_request(issue_key, transition_id, comment=None) - Transicionar solicitud a un nuevo estado

Gestión de aprobaciones y participantes

  • servicedesk_get_approvals(issue_key) - Obtener información de aprobación para la solicitud
  • servicedesk_approve_request(issue_key, approval_id, decision) - Aprobar o rechazar aprobación de solicitud
  • servicedesk_get_participants(issue_key) - Obtener participantes de la solicitud
  • servicedesk_add_participants(issue_key, usernames) - Agregar participantes a la solicitud (con mensajes de confirmación)
  • servicedesk_manage_notifications(issue_key, subscribe) - Suscribirse/cancelar suscripción a notificaciones de solicitud

Solución de problemas

Problemas de autenticación

  • Asegúrese de que la URI de redirección coincida exactamente: http://localhost:8080/callback
  • Verifique que todos los alcances requeridos estén configurados en la Consola de desarrolladores de Atlassian
  • Verifique que las variables de entorno estén configuradas correctamente

Problemas de permisos

  • Asegúrese de que su usuario tenga acceso apropiado a Jira y Confluence
  • Verifique que la aplicación OAuth tenga todos los alcances requeridos habilitados
  • Verifique que el usuario esté en los grupos correctos (por ejemplo, confluence-users)

Errores de API

  • Verifique que la URL de su sitio de Atlassian sea correcta
  • Asegúrese de tener permisos adecuados para los recursos a los que accede
  • Ejecute los scripts de prueba para verificar la funcionalidad

Requisitos de alcances

Este servidor MCP utiliza alcances mínimos requeridos siguiendo el principio de privilegio mínimo:

Alcances esenciales (16 en total)

  • Jira: read:jira-work, read:jira-user, write:jira-work
  • Confluence: read:page:confluence, read:space:confluence, write:page:confluence, read:comment:confluence, write:comment:confluence, read:label:confluence, read:attachment:confluence
  • Gestión de servicios: read:servicedesk-request, write:servicedesk-request, manage:servicedesk-customer, read:knowledgebase:jira-service-management
  • Principal: read:me, offline_access

Alcances opcionales (agregue solo si es necesario)

  • Alcances de manage:* - Solo para operaciones administrativas

Importante: Alcances granulares para API v2

Este servidor MCP utiliza alcances granulares para operaciones de Confluence para garantizar la compatibilidad con los endpoints de la API v2 de Confluence. La API v2 proporciona mejor rendimiento y preparación para el futuro en comparación con la API REST v1 obsoleta.

Alcances granulares vs clásicos:

  • Granular (recomendado): read:page:confluence, write:page:confluence - Funciona con API v2
  • Clásico (obsoleto): read:confluence-content.all, write:confluence-content - Solo funciona con API v1

Si configuró previamente alcances clásicos, deberá actualizar su aplicación OAuth para usar alcances granulares y volver a autenticarse para obtener tokens nuevos.

Seguridad de la cadena de suministro

Este proyecto implementa medidas integrales de seguridad en la cadena de suministro:

Gestión de Dependencias

  • Versiones Fijadas: Todas las dependencias utilizan versiones exactas fijadas para evitar actualizaciones inesperadas
  • Escaneo de Seguridad: Escaneo automatizado de vulnerabilidades con Safety y pip-audit
  • Seguimiento de Dependencias: Documentación completa de dependencias en docs/DEPENDENCIES.md
  • Actualizaciones Regulares: Verificaciones de seguridad automatizadas semanales mediante GitHub Actions

Herramientas de Seguridad

# Generate dependency report
python3 scripts/generate_dependency_report.py

# Check for vulnerabilities
pip3 install safety pip-audit
safety check
pip-audit

# Update dependencies safely
python3 scripts/update_dependencies.py

Archivos

  • requirements.txt - Dependencias de producción fijadas
  • docs/DEPENDENCIES.md - Informe de dependencias legible para humanos
  • docs/dependency-report.json - Datos de dependencias legibles por máquina
  • SECURITY.md - Política de seguridad y respuesta a vulnerabilidades
  • .github/workflows/dependency-security.yml - Verificaciones de seguridad automatizadas

Desarrollo

El servidor está construido utilizando:

  • FastMCP: Marco moderno de servidor MCP
  • httpx: Cliente HTTP asíncrono
  • Pydantic: Validación de datos y gestión de configuraciones

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.