atlassian-browser-mcp

Envoltorio MCP respaldado por navegador para mcp-atlassian con autenticación SSO de Playwright. Permite que herramientas de IA accedan a instancias de Atlassian Server/Data Center detrás de SSO corporativo (Okta, SAML, ADFS) donde no hay tokens de API disponibles.

GitHub

Prueba este MCPPatrocinado

Documentación

atlassian-browser-mcp

Servidor MCP que envuelve el conjunto de herramientas upstream mcp-atlassian con autenticación mediante cookies de navegador a través de Playwright. Diseñado para instancias de Atlassian Server/Data Center detrás de SSO corporativo (Okta, SAML, etc.) donde no hay tokens de API disponibles.

Cómo funciona

La autenticación y el servicio son dos procesos separados — esto es lo que evita que el servidor MCP se cuelgue:

Autentícate con la CLI (en primer plano, donde un navegador puede abrirse): atlassian-cli login <jira|confluence> ejecuta Playwright, completas el SSO/MFA una vez, y las cookies se guardan en un archivo de estado de almacenamiento por servicio.
El servidor MCP solo sirve datos. Lee las cookies guardadas mediante una subclase personalizada de requests.Session y nunca abre un navegador. Si la sesión falta o ha expirado, falla rápidamente con un AuthRequiredError indicándote que ejecutes el inicio de sesión CLI — no se bloquea esperando un inicio de sesión interactivo.

⚠️ Las versiones anteriores lanzaban el navegador de inicio de sesión desde dentro del servidor. Como el servidor está separado y es asíncrono, eso bloqueaba las llamadas a herramientas durante minutos (a menudo para siempre) y podía bloquear la API síncrona de Playwright en el bucle de eventos. La división CLI/servidor (allow_interactive=False en sesiones del servidor) elimina ese modo de fallo por completo.

El servidor aplica parches a los constructores de JiraClient y ConfluenceClient en mcp-atlassian para inyectar la sesión de cookies del navegador, ofreciendo paridad total con la superficie de herramientas upstream.

Archivos

Archivo	Propósito
`atlassian_browser_mcp_full.py`	Punto de entrada MCP. Aplica parches a los clientes upstream, registra la herramienta `atlassian_login`, ejecuta el servidor MCP
`atlassian_browser_auth.py`	Núcleo de autenticación compartido: `BrowserCookieSession`, `interactive_login()`, preparación de perfiles, detección de SSO
`atlassian_cli.py` + `atlassian-cli`	Interfaz de línea de comandos sobre el mismo núcleo de autenticación (Jira/Confluence get/search, login). Ideal para scripts y agentes — ver `AGENT_USAGE.md`
`run-atlassian-browser-mcp.sh`	Lanzador MCP: crea el venv, instala dependencias mediante `uv`, ejecuta la verificación de compatibilidad, inicia el servidor
`pyproject.toml`	Fijaciones de dependencias

Reutilizar tu sesión real del navegador (recomendado)

Para evitar volver a introducir tu nombre de usuario/contraseña + MFA en cada inicio de sesión, prepara el perfil de automatización una vez desde tu perfil real de Chrome. La copia lleva tus cookies SSO existentes (y los inicios de sesión guardados / extensión de gestor de contraseñas), por lo que el primer inicio de sesión suele ser de un clic o completamente sin intervención:

ATLASSIAN_SEED_FROM_CHROME_PROFILE=Default ./atlassian-cli login jira

Chrome 136+ bloquea la automatización para manejar el perfil en vivo en su lugar, por lo que una copia única en el directorio de perfil dedicado es la forma compatible de heredar la sesión. El perfil nunca se elimina automáticamente en un fallo de autenticación, por lo que la sesión de larga duración persiste y el reinicio de sesión sigue siendo instantáneo. Jira y Confluence mantienen archivos de cookies separados pero comparten un perfil preparado.

Uso de la CLI

export JIRA_URL="https://jira.example.com"
export CONFLUENCE_URL="https://confluence.example.com"

./atlassian-cli login jira                       # one-time per service
./atlassian-cli jira get PROJ-123 --comments
./atlassian-cli jira search 'project = PROJ AND status = "In Progress"'
./atlassian-cli confluence get 123456789 --markdown -o page.md
./atlassian-cli confluence search 'release process' --space DEV

La CLI usa por defecto el canal real de chrome (sus cookies preparadas están cifradas con una clave de llavero que solo Chrome puede leer); el servidor MCP usa por defecto chromium.

Uso

./run-atlassian-browser-mcp.sh

Configuración del servidor MCP

Añade a tu configuración de cliente MCP de Claude Code, Cursor u otro:

{
  "mcpServers": {
    "atlassian": {
      "command": "/path/to/atlassian-browser-mcp/run-atlassian-browser-mcp.sh",
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "CONFLUENCE_URL": "https://confluence.example.com",
        "ATLASSIAN_USERNAME": "your.email@company.com"
      }
    }
  }
}

En el primer uso (o cuando las cookies expiren), se abre una ventana de Chromium para el inicio de sesión SSO. Después de completar el inicio de sesión, el navegador se cierra automáticamente y todas las llamadas a herramientas MCP proceden usando la sesión guardada.

Variables de entorno

Variable	Predeterminado	Descripción
`JIRA_URL`	(obligatoria)	URL base de Jira (p. ej. `https://jira.example.com`)
`CONFLUENCE_URL`	(obligatoria)	URL base de Confluence (p. ej. `https://confluence.example.com`)
`ATLASSIAN_BROWSER_AUTH_ENABLED`	`true`	Habilitar autenticación por navegador (establece `false` para volver a la autenticación por token)
`ATLASSIAN_BROWSER_PROFILE_DIR`	`./.atlassian-browser-profile`	Directorio de perfil de navegador persistente (compartido entre servicios)
`ATLASSIAN_SEED_FROM_CHROME_PROFILE`	(ninguno)	Prepara el perfil una vez desde un perfil real de Chrome (nombre como `Default`/`Profile 1`, o una ruta absoluta). Trae tus cookies, inicios de sesión guardados y sesión SSO existente
`ATLASSIAN_CHROME_USER_DATA_DIR`	(directorio de Chrome en macOS)	Dónde viven los perfiles de Chrome, para resolver el nombre del perfil de preparación
`ATLASSIAN_STORAGE_STATE`	`./.atlassian-browser-state-{service}.json`	Archivo de cookies. Por servicio por defecto; un valor explícito sigue teniendo espacio de nombres por servicio
`ATLASSIAN_LOGIN_TIMEOUT_SECONDS`	`300`	Segundos para esperar el inicio de sesión manual
`ATLASSIAN_USERNAME`	(ninguno)	Opcional: prellenar el nombre de usuario en la página SSO
`ATLASSIAN_SSO_MARKERS`	(automático)	Marcadores de URL/texto separados por comas para la detección de redirección SSO. Los valores predeterminados cubren Okta, ADFS, Azure AD, PingOne, Google SAML
`ATLASSIAN_BROWSER_CHANNEL`	`chromium`	Canal del navegador (`chromium`, `chrome`, `msedge`)
`ATLASSIAN_JIRA_LOGIN_URL`	`{JIRA_URL}/secure/Dashboard.jspa`	Sobrescribir la URL del punto de entrada de inicio de sesión de Jira
`ATLASSIAN_CONFLUENCE_LOGIN_URL`	`{CONFLUENCE_URL}`	Sobrescribir la URL del punto de entrada de inicio de sesión de Confluence
`ATLASSIAN_BROWSER_USER_AGENT`	(Chrome 136)	Cadena de User-Agent personalizada para solicitudes de API
`TOOLSETS`	`all`	Qué conjuntos de herramientas upstream habilitar

Requisitos

Python 3.11+
uv (para la gestión de dependencias)
Chromium (instalado automáticamente por Playwright)
Una pantalla gráfica (macOS, X11 o Wayland) — necesaria para el inicio de sesión SSO interactivo
Acceso de red a tu instancia de Atlassian

Solución de problemas

Síntoma	Causa	Solución
El navegador no se abre	Entorno sin pantalla (SSH, Docker)	Reenvía X11 o ejecuta el inicio de sesión inicial en una máquina con pantalla
El inicio de sesión agotó el tiempo	No llegaste a la URL de Jira/Confluence en 300s	Comprueba que `JIRA_URL`/`CONFLUENCE_URL` coinciden exactamente con dónde redirige tu IdP después del inicio de sesión. Aumenta `ATLASSIAN_LOGIN_TIMEOUT_SECONDS` si es necesario
Las herramientas devuelven HTML en lugar de JSON	Sesión expirada, marcadores SSO no coinciden con tu IdP	Establece `ATLASSIAN_SSO_MARKERS` con el patrón de URL de tu IdP
"La verificación de compatibilidad upstream falló"	La versión de `mcp-atlassian` cambió su API interna	Fija una versión compatible o actualiza el envoltorio
"El ejecutable no existe"	Playwright Chromium no está instalado	Ejecuta `python -m playwright install chromium`