atlassian-browser-mcp

License: GPL-3.0 Python 3.11+ GitHub stars mcp-atlassian GeiserX/atlassian-browser-mcp MCP server

MCP server that wraps the upstream mcp-atlassian toolset with browser-cookie authentication via Playwright. Designed for Atlassian Server/Data Center instances behind corporate SSO (Okta, SAML, etc.) where API tokens are not available.

How it works

Authentication and serving are two separate processes — this is what keeps the MCP server from hanging:

1. Authenticate with the CLI (foreground, where a browser can open): atlassian-cli login <jira|confluence> runs Playwright, you complete SSO/MFA once, and cookies are saved to a per-service storage-state file.
2. The MCP server serves data only. It reads the saved cookies via a custom requests.Session subclass and never opens a browser. On a missing/expired session it fails fast with an AuthRequiredError telling you to run the CLI login — it does not block waiting for an interactive login.

⚠️ Earlier versions launched the login browser from inside the server. Because the server is detached and async, that blocked tool calls for minutes (often forever) and could deadlock Playwright's sync API on the event loop. The CLI/server split (allow_interactive=False on server sessions) removes that failure mode entirely.

The server monkey-patches JiraClient and ConfluenceClient constructors in mcp-atlassian to inject the browser-cookie session, giving full parity with the upstream tool surface.

Files

File	Purpose
atlassian_browser_mcp_full.py	MCP entrypoint. Patches upstream clients, registers atlassian_login tool, runs the MCP server
atlassian_browser_auth.py	Shared auth core: BrowserCookieSession, interactive_login(), profile seeding, SSO detection
atlassian_cli.py + atlassian-cli	Command-line front-end over the same auth core (Jira/Confluence get/search, login). Great for scripts and agents — see AGENT_USAGE.md
run-atlassian-browser-mcp.sh	MCP launcher: creates venv, installs deps via uv, runs compatibility check, starts server
pyproject.toml	Dependency pins

Reusing your real browser session (recommended)

To avoid re-entering your username/password + MFA on every login, seed the automation profile once from your real Chrome profile. The copy carries your existing SSO cookies (and saved logins / password-manager extension), so the first login is typically one-click or fully hands-free:

ATLASSIAN_SEED_FROM_CHROME_PROFILE=Default ./atlassian-cli login jira

Chrome 136+ blocks automation from driving the live profile in place, so a one-time copy into the dedicated profile dir is the supported way to inherit the session. The profile is never auto-deleted on an auth failure, so the long-lived session persists and re-login stays instant. Jira and Confluence keep separate cookie jars but share one seeded profile.

CLI usage

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

The CLI defaults to the real chrome channel (its seeded cookies are encrypted with a keychain key only Chrome can read); the MCP server defaults to chromium.

Usage

./run-atlassian-browser-mcp.sh

MCP server configuration

Add to your Claude Code, Cursor, or other MCP client configuration:

{
  "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": "[email protected]"
      }
    }
  }
}

On first use (or when cookies expire), a Chromium window opens for SSO login. After login completes, the browser closes automatically and all MCP tool calls proceed using the saved session.

Environment variables

Variable	Default	Description
JIRA_URL	(required)	Jira base URL (e.g. https://jira.example.com)
CONFLUENCE_URL	(required)	Confluence base URL (e.g. https://confluence.example.com)
ATLASSIAN_BROWSER_AUTH_ENABLED	true	Enable browser auth (set false to fall back to token auth)
ATLASSIAN_BROWSER_PROFILE_DIR	./.atlassian-browser-profile	Persistent browser profile directory (shared across services)
ATLASSIAN_SEED_FROM_CHROME_PROFILE	(none)	Seed the profile once from a real Chrome profile (name like Default/Profile 1, or an absolute path). Brings your cookies, saved logins, and existing SSO session
ATLASSIAN_CHROME_USER_DATA_DIR	(macOS Chrome dir)	Where Chrome profiles live, for resolving the seed profile name
ATLASSIAN_STORAGE_STATE	./.atlassian-browser-state-{service}.json	Cookie-jar file. Per-service by default; an explicit value is still namespaced per service
ATLASSIAN_LOGIN_TIMEOUT_SECONDS	300	Seconds to wait for manual login
ATLASSIAN_USERNAME	(none)	Optional: prefill username on SSO page
ATLASSIAN_SSO_MARKERS	(auto)	Comma-separated URL/text markers for SSO redirect detection. Defaults cover Okta, ADFS, Azure AD, PingOne, Google SAML
ATLASSIAN_BROWSER_CHANNEL	chromium	Browser channel (chromium, chrome, msedge)
ATLASSIAN_JIRA_LOGIN_URL	{JIRA_URL}/secure/Dashboard.jspa	Override the Jira login entry point URL
ATLASSIAN_CONFLUENCE_LOGIN_URL	{CONFLUENCE_URL}	Override the Confluence login entry point URL
ATLASSIAN_BROWSER_USER_AGENT	(Chrome 136)	Custom User-Agent string for API requests
TOOLSETS	all	Which upstream toolsets to enable

Requirements

• Python 3.11+
• uv (for dependency management)
• Chromium (installed automatically by Playwright)
• A graphical display (macOS, X11, or Wayland) — required for interactive SSO login
• Network access to your Atlassian instance

Troubleshooting

Symptom	Cause	Fix
Browser doesn't open	Headless environment (SSH, Docker)	Forward X11 or run initial login on a machine with a display
Login timed out	Didn't land on Jira/Confluence URL within 300s	Check JIRA_URL/CONFLUENCE_URL match exactly where your IdP redirects after login. Increase ATLASSIAN_LOGIN_TIMEOUT_SECONDS if needed
Tools return HTML instead of JSON	Session expired, SSO markers not matching your IdP	Set ATLASSIAN_SSO_MARKERS with your IdP's URL pattern
"Upstream compatibility check failed"	mcp-atlassian version changed its internal API	Pin to a compatible version or update the wrapper
"Executable doesn't exist"	Playwright Chromium not installed	Run python -m playwright install chromium