atlassian-browser-mcp

Wrapper MCP com suporte a navegador para mcp-atlassian com autenticação SSO via Playwright. Permite que ferramentas de IA acessem instâncias do Atlassian Server/Data Center protegidas por SSO corporativo (Okta, SAML, ADFS) onde tokens de API não estão disponíveis.

GitHub

Experimente este MCPPatrocinado

Documentação

atlassian-browser-mcp

Servidor MCP que encapsula o conjunto de ferramentas upstream mcp-atlassian com autenticação por cookies de navegador via Playwright. Projetado para instâncias Atlassian Server/Data Center atrás de SSO corporativo (Okta, SAML, etc.) onde tokens de API não estão disponíveis.

Como funciona

Autenticação e serviço são dois processos separados — é isso que impede o servidor MCP de travar:

Autentique-se com a CLI (em primeiro plano, onde um navegador pode abrir): atlassian-cli login <jira|confluence> executa o Playwright, você completa o SSO/MFA uma vez, e os cookies são salvos em um arquivo de estado de armazenamento por serviço.
O servidor MCP serve apenas dados. Ele lê os cookies salvos via uma subclasse personalizada de requests.Session e nunca abre um navegador. Em sessão ausente/expirada, ele falha rapidamente com um AuthRequiredError informando para você executar o login via CLI — ele não bloqueia aguardando um login interativo.

⚠️ Versões anteriores lançavam o navegador de login de dentro do servidor. Como o servidor é destacado e assíncrono, isso bloqueava chamadas de ferramentas por minutos (frequentemente para sempre) e podia travar a API síncrona do Playwright no loop de eventos. A divisão CLI/servidor (allow_interactive=False em sessões de servidor) elimina completamente esse modo de falha.

O servidor aplica monkey-patch nos construtores de JiraClient e ConfluenceClient em mcp-atlassian para injetar a sessão de cookies do navegador, dando paridade total com a superfície de ferramentas upstream.

Arquivos

Arquivo	Finalidade
`atlassian_browser_mcp_full.py`	Ponto de entrada do MCP. Aplica patches nos clientes upstream, registra a ferramenta `atlassian_login`, executa o servidor MCP
`atlassian_browser_auth.py`	Núcleo de autenticação compartilhado: `BrowserCookieSession`, `interactive_login()`, propagação de perfil, detecção de SSO
`atlassian_cli.py` + `atlassian-cli`	Interface de linha de comando sobre o mesmo núcleo de autenticação (busca/consulta e login no Jira/Confluence). Ótimo para scripts e agentes — veja `AGENT_USAGE.md`
`run-atlassian-browser-mcp.sh`	Lançador do MCP: cria venv, instala dependências via `uv`, executa verificação de compatibilidade, inicia o servidor
`pyproject.toml`	Fixação de dependências

Reutilizando sua sessão real do navegador (recomendado)

Para evitar digitar novamente seu usuário/senha + MFA a cada login, propague o perfil de automação uma vez a partir do seu perfil real do Chrome. A cópia carrega seus cookies de SSO existentes (e logins salvos / extensão de gerenciador de senhas), então o primeiro login é tipicamente de um clique ou totalmente sem intervenção:

ATLASSIAN_SEED_FROM_CHROME_PROFILE=Default ./atlassian-cli login jira

O Chrome 136+ bloqueia a automação de dirigir o perfil ativo no lugar, então uma cópia única para o diretório de perfil dedicado é a forma suportada de herdar a sessão. O perfil nunca é excluído automaticamente em uma falha de autenticação, então a sessão de longa duração persiste e o re-login permanece instantâneo. Jira e Confluence mantêm jarros de cookies separados, mas compartilham um perfil propagado.

Uso da 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

A CLI usa por padrão o canal real chrome (seus cookies propagados são criptografados com uma chave do keychain que apenas o Chrome pode ler); o servidor MCP usa por padrão chromium.

Uso

./run-atlassian-browser-mcp.sh

Configuração do servidor MCP

Adicione à configuração do seu cliente MCP no Claude Code, Cursor ou outro:

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

No primeiro uso (ou quando os cookies expirarem), uma janela do Chromium abre para login SSO. Após o login ser concluído, o navegador fecha automaticamente e todas as chamadas de ferramentas MCP prosseguem usando a sessão salva.

Variáveis de ambiente

Variável	Padrão	Descrição
`JIRA_URL`	(obrigatório)	URL base do Jira (ex.: `https://jira.example.com`)
`CONFLUENCE_URL`	(obrigatório)	URL base do Confluence (ex.: `https://confluence.example.com`)
`ATLASSIAN_BROWSER_AUTH_ENABLED`	`true`	Habilita autenticação por navegador (defina `false` para voltar à autenticação por token)
`ATLASSIAN_BROWSER_PROFILE_DIR`	`./.atlassian-browser-profile`	Diretório de perfil persistente do navegador (compartilhado entre serviços)
`ATLASSIAN_SEED_FROM_CHROME_PROFILE`	(nenhum)	Propaga o perfil uma vez a partir de um perfil real do Chrome (nome como `Default`/`Profile 1`, ou um caminho absoluto). Traz seus cookies, logins salvos e sessão SSO existente
`ATLASSIAN_CHROME_USER_DATA_DIR`	(diretório Chrome do macOS)	Onde os perfis do Chrome ficam, para resolver o nome do perfil de propagação
`ATLASSIAN_STORAGE_STATE`	`./.atlassian-browser-state-{service}.json`	Arquivo de jarro de cookies. Por serviço por padrão; um valor explícito ainda é namespaced por serviço
`ATLASSIAN_LOGIN_TIMEOUT_SECONDS`	`300`	Segundos para aguardar o login manual
`ATLASSIAN_USERNAME`	(nenhum)	Opcional: pré-preenche o nome de usuário na página SSO
`ATLASSIAN_SSO_MARKERS`	(automático)	Marcadores de URL/texto separados por vírgula para detecção de redirecionamento SSO. Os padrões cobrem Okta, ADFS, Azure AD, PingOne, Google SAML
`ATLASSIAN_BROWSER_CHANNEL`	`chromium`	Canal do navegador (`chromium`, `chrome`, `msedge`)
`ATLASSIAN_JIRA_LOGIN_URL`	`{JIRA_URL}/secure/Dashboard.jspa`	Substitui a URL do ponto de entrada de login do Jira
`ATLASSIAN_CONFLUENCE_LOGIN_URL`	`{CONFLUENCE_URL}`	Substitui a URL do ponto de entrada de login do Confluence
`ATLASSIAN_BROWSER_USER_AGENT`	(Chrome 136)	String de User-Agent personalizada para requisições de API
`TOOLSETS`	`all`	Quais conjuntos de ferramentas upstream habilitar

Requisitos

Python 3.11+
uv (para gerenciamento de dependências)
Chromium (instalado automaticamente pelo Playwright)
Um display gráfico (macOS, X11 ou Wayland) — necessário para login SSO interativo
Acesso de rede à sua instância Atlassian

Solução de problemas

Sintoma	Causa	Correção
O navegador não abre	Ambiente headless (SSH, Docker)	Encaminhe X11 ou execute o login inicial em uma máquina com display
Login expirou	Não chegou à URL do Jira/Confluence dentro de 300s	Verifique se `JIRA_URL`/`CONFLUENCE_URL` correspondem exatamente aonde seu IdP redireciona após o login. Aumente `ATLASSIAN_LOGIN_TIMEOUT_SECONDS` se necessário
Ferramentas retornam HTML em vez de JSON	Sessão expirada, marcadores SSO não correspondem ao seu IdP	Defina `ATLASSIAN_SSO_MARKERS` com o padrão de URL do seu IdP
"Falha na verificação de compatibilidade upstream"	A versão de `mcp-atlassian` mudou sua API interna	Fixe em uma versão compatível ou atualize o wrapper
"Executável não existe"	Playwright Chromium não instalado	Execute `python -m playwright install chromium`