<p align="center"> <img src="docs/images/banner.svg" alt="atlassian-browser-mcp banner" width="900"/> </p>

atlassian-browser-mcp

MCP server that wraps the upstream mcp-atlassian toolset with browser-cookie authentication. Cookies are captured from your real Chrome by a bundled Chrome extension — no Playwright, no browser automation. Works for Atlassian Cloud (*.atlassian.net) and Server/Data Center behind corporate SSO (Okta, SAML, etc.) where API tokens are not available.

How it works

Capturing cookies and serving data are separate, and there is no browser automation anywhere — this is what keeps the MCP server from hanging:

1. Capture cookies with the Chrome extension. Load chrome-extension/ unpacked. After a one-time atlassian-cli install-host, open a Jira/Confluence tab and click Sync cookies — cookies for the current tab’s domain go to a local Native Messaging host that writes per-service jars.
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 re-sync — it does not block.

⚠️ Earlier versions launched a Playwright 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. Moving capture to the extension removes that failure mode — and removes the need to read Chrome's on-disk cookie DB, which Chrome 127+ "app-bound" encryption blocks.

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, saved-jar loading, write_storage_state/probe_live, SSO detection. Never opens a browser
atlassian_cli.py + atlassian-cli	Command-line front-end (install-host, import, Jira/Confluence get/search). See AGENT_USAGE.md
atlassian_cookie_import.py	Shared cookie → jar import + liveness probe (CLI and native host)
atlassian_native_host.py + atlassian-native-host	Chrome Native Messaging host for one-click Sync
chrome-extension/	Manifest V3 extension: Sync current-tab cookies via native host — see chrome-extension/README.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 Chrome session (the Chrome extension)

Modern Chrome (127+) encrypts cookies with an app-bound key that can't be read off disk, so the reliable way to reuse your Chrome SSO session is the bundled extension — it reads cookies from Chrome's live cookie store, no password or MFA re-prompt:

1. export JIRA_URL=… CONFLUENCE_URL=… then ./atlassian-cli install-host (registers the native host; freezes URLs for Chrome-launched processes).
2. chrome://extensions → enable Developer mode → Load unpacked → select chrome-extension/ → reload after install-host.
3. Open a Jira/Confluence tab, click the extension → Sync cookies.

Cookie jars are never auto-deleted on an auth failure. Jira and Confluence keep separate jars; on Atlassian Cloud they share one host, so a single sync covers both. See chrome-extension/README.md for details and the managed-Chrome caveat.

CLI usage

export JIRA_URL="https://yourco.atlassian.net"
export CONFLUENCE_URL="https://yourco.atlassian.net"   # Cloud: same host

./atlassian-cli install-host                               # once per machine
# then: open Jira/Confluence tab → extension → Sync cookies

./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

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://yourco.atlassian.net",
        "CONFLUENCE_URL": "https://yourco.atlassian.net"
      }
    }
  }
}

The server never opens a browser. Capture cookies once with the extension Sync (or import); all MCP tool calls then proceed using the saved session, and a missing/expired session fails fast with a clear re-sync message.

Environment variables

Variable	Default	Description
JIRA_URL	(required)	Jira base URL (e.g. https://yourco.atlassian.net)
CONFLUENCE_URL	(required)	Confluence base URL (e.g. https://yourco.atlassian.net). For Cloud (*.atlassian.net) the /wiki context path is appended automatically
ATLASSIAN_BROWSER_AUTH_ENABLED	true	Enable browser-cookie auth (set false to fall back to token auth)
ATLASSIAN_STORAGE_STATE	./.atlassian-browser-state-{service}.json	Cookie-jar file. Per-service by default; an explicit value is still namespaced per service
ATLASSIAN_SSO_MARKERS	(auto)	Comma-separated URL/text markers for SSO redirect detection. Defaults cover Okta, ADFS, Azure AD, PingOne, Google SAML
ATLASSIAN_BROWSER_USER_AGENT	(Chrome 136)	Custom User-Agent string for API requests and liveness probes
TOOLSETS	all	Which upstream toolsets to enable

Requirements

• Python 3.11+
• uv (for dependency management)
• Google Chrome (or another Chromium-family browser) to run the extension and capture the session
• Network access to your Atlassian instance

Troubleshooting

Symptom	Cause	Fix
Tools return AuthRequiredError / "not authenticated"	No saved session (jar missing or expired)	Extension Sync (after install-host), or atlassian-cli import <file>
import reports HTTP 401/302 (not live)	Exported cookies are already expired	Sign into Jira/Confluence in Chrome, re-Export, and import again
No cookies match your hosts on import	JIRA_URL/CONFLUENCE_URL don't match the exported cookies' domain	Fix the env vars to point at the same instance you exported from
"Load unpacked" is greyed out	Managed/corporate Chrome blocks unpacked extensions	Ask IT to allowlist the extension, or pack & self-host it (see chrome-extension/README.md)
"Upstream compatibility check failed"	mcp-atlassian version changed its internal API	Pin to a compatible version or update the wrapper