@jourlez/atlassian-mcp-server

A multi-tenant MCP proxy that connects all your Atlassian Cloud workspaces simultaneously to any MCP-compatible AI client. Built on top of the official Atlassian MCP endpoint — all auth, permissions, and data access go through Atlassian's own infrastructure.

• Simultaneous multi-account — all tenants connect at startup, routing is automatic
• Zero config switching — the AI never needs to know which account to use
• OAuth 2.1 via browser, tokens stored in ~/.mcp-auth/
• Config stored in ~/.atlassian-mcp/accounts.json — survives package updates and npx cache clears

Requirements: Node.js v22+ · An Atlassian Cloud site (Jira, Confluence, and/or Compass)

Quick start

1. Configure your MCP client

VS Code — create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "atlassian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@jourlez/atlassian-mcp-server"]
    }
  }
}

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@jourlez/atlassian-mcp-server"]
    }
  }
}

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@jourlez/atlassian-mcp-server"]
    }
  }
}

2. Add your Atlassian account(s)

Restart your client, then ask the AI:

"Add my Atlassian account at https://my-company.atlassian.net"

The AI calls atlassian_add_account, a browser window opens for OAuth consent, and your account is saved to ~/.atlassian-mcp/accounts.json. Repeat for each workspace you want to connect.

Managing accounts

Ask the AI directly — no terminal needed:

• "List my Atlassian accounts" → calls atlassian_list_accounts
• "Add my Atlassian account at https://my-company.atlassian.net" → calls atlassian_add_account
• "Remove the acme account" → calls atlassian_remove_account

To clear stored OAuth tokens, use atlassian-mcp-accounts logout from the terminal — there is no AI tool for that.

Prefer the terminal? Install the CLI:

npm install -g @jourlez/atlassian-mcp-server

atlassian-mcp-accounts          # interactive menu
atlassian-mcp-accounts list     # show all configured tenants
atlassian-mcp-accounts add      # add a new tenant
atlassian-mcp-accounts remove   # remove a tenant
atlassian-mcp-accounts logout   # clear stored OAuth tokens (~/.mcp-auth)

Config is stored in ~/.atlassian-mcp/accounts.json. You can also set ATLASSIAN_MCP_CONFIG=/path/to/accounts.json to override the location.

Example accounts.json

{
  "accounts": {
    "my-company": {
      "tenantUrl": "https://my-company.atlassian.net/",
      "label": "My Company",
      "projects": ["PROJ", "BACKEND"],
      "spaces": ["DEV", "OPS"]
    },
    "client-workspace": {
      "tenantUrl": "https://client-workspace.atlassian.net/",
      "label": "Client Workspace",
      "projects": ["DEMO"],
      "spaces": []
    }
  }
}

projects and spaces enable direct routing without fan-out — list the Jira project keys and Confluence space keys that live on each site.

How routing works

The proxy connects all tenants simultaneously. For each tool call it resolves the target tenant using this priority chain:

1. cloudId argument → exact match
2. Issue key prefix → DCC-123 maps to whichever tenant owns project DCC
3. Explicit projectKey / spaceKey argument
4. JQL/CQL project = "KEY" clause
5. Fan-out to all tenants → first non-error wins
   (getAccessibleAtlassianResources merges results from all tenants)

MCP tools exposed

In addition to the full Atlassian MCP tool suite, the proxy exposes three management tools the AI can use directly:

| Tool | Description | |---|---| | atlassian_list_accounts | Show all configured tenants and their connection status | | atlassian_add_account | Add a new tenant and trigger OAuth consent | | atlassian_remove_account | Remove a tenant and disconnect it |

Tips

Speed up tool calls with explicit routing hints

Add this to your AGENTS.md or system prompt to eliminate discovery overhead:

## Atlassian MCP
- Default Jira project: YOURPROJ
- Default Confluence space: ENG
- cloudId: https://yoursite.atlassian.net (skip getAccessibleAtlassianResources)
- Use maxResults: 10 for all JQL/CQL searches

Skills

Pre-built prompt skills for common workflows (status reports, triage, backlog generation) are in the skills/ directory.

Troubleshooting

| Symptom | Fix | |---|---| | could not determine executable to run | rm -rf ~/.npm/_npx then restart | | Config error on startup | Ask the AI to add your account, or run atlassian-mcp-accounts add | | OAuth browser window doesn't open | Check client logs for the auth URL and open it manually | | Only one tenant's tools visible | Run atlassian_list_accounts — additional tenants connect on first use | | 403 Forbidden on tool calls | Your Atlassian admin may need to enable Rovo MCP for your org |

Security

All traffic goes through https://mcp.atlassian.com over TLS. OAuth tokens are stored locally in ~/.mcp-auth/ and never leave your machine. Data access respects your existing Atlassian project/space permissions.

LLMs are vulnerable to prompt injection. Only connect trusted MCP clients and review high-impact actions before confirming. See Atlassian's MCP risk guidance.

License

Apache 2.0 — forked from atlassian/atlassian-mcp-server