MCP Atlassian

Servidor de Protocolo de Contexto de Modelo (MCP) para productos de Atlassian (Confluence y Jira). Esta integración es compatible con las implementaciones de Confluence y Jira Cloud y de servidor/centro de datos.

Ejemplo de uso

Pídale a su asistente de IA que:

• Actualizaciones automáticas de Jira : "Actualizar Jira desde las notas de la reunión"

• Búsqueda en Confluence con IA : "Encuentra nuestra guía OKR en Confluence y resúmela"

• Filtrado inteligente de incidencias de Jira : "Muéstrame errores urgentes en el proyecto PROJ de la semana pasada"

• 📄 Creación y gestión de contenido : "Crear un documento de diseño técnico para la función XYZ"

Demostración de funciones

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

Compatibilidad

Related MCP server: MCP Atlassian

Guía de inicio rápido

🔐 1. Configuración de autenticación

MCP Atlassian admite tres métodos de autenticación:

A. Autenticación mediante token API (nube)

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

2. Haga clic en Crear token de API y asígnele un nombre.

3. Copiar el token inmediatamente

B. Token de acceso personal (Servidor/Centro de datos)

1. Vaya a su perfil (avatar) → Perfil → Tokens de acceso personal

2. Haga clic en Crear token , asígnele un nombre y configure la fecha de caducidad.

3. Copiar el token inmediatamente

C. Autenticación OAuth 2.0 (nube)

1. Vaya a la consola para desarrolladores de Atlassian

2. Crear una aplicación de "integración OAuth 2.0 (3LO)"

3. Configurar permisos (ámbitos) para Jira/Confluence

4. Establecer URL de devolución de llamada (por ejemplo, http://localhost:8080/callback )

5. Ejecutar el asistente de configuración:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

6. Siga las indicaciones para Client ID , Secret , URI y Scope

7. Autorización completa del navegador

8. Agregue las credenciales obtenidas a .env o a la configuración IDE:

   • ATLASSIAN_OAUTH_CLOUD_ID (del asistente)

   • ATLASSIAN_OAUTH_CLIENT_ID

   • ATLASSIAN_OAUTH_CLIENT_SECRET

   • ATLASSIAN_OAUTH_REDIRECT_URI

   • ATLASSIAN_OAUTH_SCOPE

[!IMPORTANTE] Incluir offline_access en el alcance para la autenticación persistente (por ejemplo, read:jira-work write:jira-work offline_access )

📦 2. Instalación

MCP Atlassian se distribuye como una imagen de Docker. Esta es la forma recomendada de ejecutar el servidor, especialmente para la integración con IDE. Asegúrese de tener Docker instalado.

# Pull Pre-built Image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

🛠️ Integración IDE

MCP Atlassian está diseñado para usarse con asistentes de IA a través de la integración IDE.

[!TIP] Para Claude Desktop : Localice y edite el archivo de configuración directamente:

• Ventanas : %APPDATA%\Claude\claude_desktop_config.json

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux : ~/.config/Claude/claude_desktop_config.json

Para el cursor : Abra Configuración → MCP → + Agregar nuevo servidor MCP global

⚙️ Métodos de configuración

Hay dos enfoques principales para configurar el contenedor Docker:

1. Pasar variables directamente (mostradas en los ejemplos a continuación)

2. Uso de un archivo de entorno con el indicador --env-file (mostrado en secciones plegables)

[!NOTA] Las variables de entorno comunes incluyen:

• CONFLUENCE_SPACES_FILTER : Filtrar por claves de espacio (p. ej., "DEV,TEAM,DOC")

• JIRA_PROJECTS_FILTER : Filtrar por claves de proyecto (p. ej., "PROJ,DEV,SUPPORT")

• READ_ONLY_MODE : Establézcalo en "verdadero" para deshabilitar las operaciones de escritura

• MCP_VERBOSE : Establézcalo en "verdadero" para un registro más detallado

• ENABLED_TOOLS : Lista separada por comas de nombres de herramientas para habilitar (por ejemplo, "confluence_search,jira_get_issue")

Consulte el archivo .env.example para ver todas las opciones disponibles.

📝 Ejemplos de configuración

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"
      }
    }
  }
}

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

Para implementaciones de servidor/centro de datos, utilice el paso directo de variables:

{
  "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"
      }
    }
  }
}

[!NOTE] Establezca CONFLUENCE_SSL_VERIFY y JIRA_SSL_VERIFY en "falso" solo si tiene certificados autofirmados.

Este ejemplo muestra cómo configurar mcp-atlassian en su IDE (como Cursor o Claude Desktop) al usar OAuth 2.0 para Atlassian Cloud. Asegúrese de haber completado primero el asistente de configuración de OAuth .

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest",
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

[!NOTA]

• ATLASSIAN_OAUTH_CLOUD_ID se obtiene de la salida del asistente --oauth-setup .

• Otras variables ATLASSIAN_OAUTH_* son aquellas que usted configuró para su aplicación OAuth en Atlassian Developer Console (y usó como entrada para el asistente de configuración).

• Aún se requieren JIRA_URL y CONFLUENCE_URL para sus instancias de Cloud.

MCP Atlassian admite el enrutamiento de solicitudes de API mediante servidores proxy HTTP/HTTPS/SOCKS estándar. Configure mediante variables de entorno:

• Admite los estándares HTTP_PROXY , HTTPS_PROXY , NO_PROXY y SOCKS_PROXY .

• Están disponibles anulaciones específicas del servicio (por ejemplo, JIRA_HTTPS_PROXY , CONFLUENCE_NO_PROXY ).

• Las variables específicas del servicio anulan las globales para ese servicio.

Agregue las variables proxy relevantes a las secciones args (usando -e ) y env de su configuración de MCP:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... existing Confluence/Jira vars",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... existing Confluence/Jira vars": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

Las credenciales de las URL de proxy se ocultan en los registros. Si se configura NO_PROXY , se respetará para las solicitudes a los hosts que coincidan.

Solo para Confluence Cloud:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_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_api_token"
      }
    }
  }
}

Para Confluence Server/DC, utilice:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

Solo para Jira Cloud:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Para Jira Server/DC, utilice:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

👥 Configuración del transporte HTTP

En lugar de utilizar stdio , puede ejecutar el servidor como un servicio HTTP persistente utilizando:

• Transporte sse (eventos enviados por el servidor) en el punto final /sse

• transporte streamable-http en el punto final /mcp

Ambos tipos de transporte admiten la autenticación de usuario único y multiusuario:

Opciones de autenticación:

• Usuario único : utilice la autenticación a nivel de servidor configurada a través de variables de entorno

• Multiusuario : cada usuario proporciona su propia autenticación:

  • Nube: Tokens portadores OAuth 2.0

  • Servidor/Centro de datos: Tokens de acceso personal (PAT)

1. Inicie el servidor con el transporte elegido:

   # For SSE transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport sse --port 9000 -vv
   
   # OR for streamable-http transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

2. Configurar su IDE (ejemplo de usuario único):

   Ejemplo de transporte SSE:

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

   Ejemplo de transporte HTTP transmisible:

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

A continuación se muestra un ejemplo completo de configuración de la autenticación multiusuario con transporte HTTP transmitible:

1. Primero, ejecute el asistente de configuración de OAuth para configurar las credenciales de OAuth del servidor:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

2. Inicie el servidor con transporte HTTP transmitible:

   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

3. Configure los ajustes MCP de su IDE:

Elija el método de autorización adecuado para su implementación de Atlassian:

• Nube (OAuth 2.0): use esta opción si su organización está en Atlassian Cloud y tiene un token de acceso OAuth para cada usuario.

• Servidor/Centro de datos (PAT): use esto si está en un servidor o centro de datos de Atlassian y cada usuario tiene un token de acceso personal (PAT).

Ejemplo de nube (OAuth 2.0):

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

Ejemplo de servidor/centro de datos (PAT):

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

4. Variables de entorno requeridas en .env :

   JIRA_URL=https://your-company.atlassian.net
   CONFLUENCE_URL=https://your-company.atlassian.net/wiki
   ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id
   ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret
   ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
   ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access
   ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

[!NOTA]

• El servidor debe tener configurada su propia autenticación de respaldo (p. ej., mediante variables de entorno para el token de API, PAT o su propia configuración de OAuth mediante --oauth-setup). Esto se utiliza si una solicitud no incluye autenticación específica del usuario.

• OAuth : cada usuario necesita su propio token de acceso OAuth desde su aplicación Atlassian OAuth.

• PAT : Cada usuario proporciona su propio token de acceso personal.

• El servidor utilizará el token del usuario para las llamadas API cuando se proporcione, recurriendo a la autenticación del servidor si no lo está.

• Los tokens de usuario deben tener alcances apropiados para las operaciones necesarias

Herramientas

Herramientas clave

Herramientas de Jira

• jira_get_issue : obtener detalles de un problema específico

• jira_search : Problemas de búsqueda con JQL

• jira_create_issue : Crea un nuevo problema

• jira_update_issue : Actualizar un problema existente

• jira_transition_issue : Transición de un problema a un nuevo estado

• jira_add_comment : Agregar un comentario a un problema

Herramientas de Confluence

• confluence_search : busca contenido de Confluence usando CQL

• confluence_get_page : Obtener el contenido de una página específica

• confluence_create_page : Crea una nueva página

• confluence_update_page : Actualizar una página existente

*Herramienta disponible únicamente en Jira Cloud

Filtrado de herramientas y control de acceso

El servidor proporciona dos formas de controlar el acceso a las herramientas:

1. Filtrado de herramientas : utilice el indicador --enabled-tools o la variable de entorno ENABLED_TOOLS para especificar qué herramientas deben estar disponibles:

   # Via environment variable
   ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
   
   # Or via command line flag
   docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

2. Control de lectura/escritura : Las herramientas se clasifican como operaciones de lectura o escritura. Cuando READ_ONLY_MODE está habilitado, solo están disponibles las operaciones de lectura, independientemente de la configuración ENABLED_TOOLS .

Solución de problemas y depuración

Problemas comunes

• Errores de autenticación :

  • Para la nube: Verifique sus tokens API (no la contraseña de su cuenta)

  • Para servidor/centro de datos: Verifique que su token de acceso personal sea válido y no esté vencido

  • Para servidores Confluence más antiguos: Algunas versiones anteriores requieren autenticación básica con CONFLUENCE_USERNAME y CONFLUENCE_API_TOKEN (donde token es su contraseña)

• Problemas con el certificado SSL : si usa un servidor o centro de datos y encuentra errores de SSL, configure CONFLUENCE_SSL_VERIFY=false o JIRA_SSL_VERIFY=false

• Errores de permisos : asegúrese de que su cuenta de Atlassian tenga permisos suficientes para acceder a los espacios/proyectos

Herramientas de depuración

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

Seguridad

• Nunca comparta tokens API

• Mantenga los archivos .env seguros y privados

• Consulte SECURITY.md para conocer las mejores prácticas

Contribuyendo

¡Agradecemos sus contribuciones a MCP Atlassian! Si desea contribuir:

1. Consulte nuestra guía CONTRIBUTING.md para obtener instrucciones detalladas de configuración del desarrollo.

2. Realizar cambios y enviar una solicitud de extracción.

Usamos ganchos previos a la confirmación para garantizar la calidad del código y seguimos el control de versiones semántico para los lanzamientos.

Licencia

Con licencia del MIT (véase el archivo de LICENCIA ). Este no es un producto oficial de Atlassian.