MCP Atlassian with Bitbucket and Privacy

Model Context Protocol (MCP) server for Atlassian products — Jira, Confluence, and Bitbucket. Supports both Cloud and Server/Data Center deployments.

162 tools across 37 toolsets: 63 Jira + 35 Confluence + 64 Bitbucket.

Fork of jellythomas/mcp-atlassian-with-bitbucket, which added comprehensive Bitbucket Cloud and Server/DC integration on top of sooperset/mcp-atlassian. This fork adds further Bitbucket Server/DC fixes (real branch-utils, build-status, branch-permissions, and code-search APIs).

Integrated upstream state:

• jellythomas/mcp-atlassian-with-bitbucket @ 9face83 (tag v1.0.5, 2026-03-13)
• sooperset/mcp-atlassian @ 2e25fb4 (52 commits past tag v0.23.0, 2026-09-15)

Quick Start

Choose one of the installation options below, then start using.

Option A: Using uvx (Recommended — No Install Required)

Just add to your Claude Desktop, Cursor, VS Code, or Claude Code MCP configuration:

{
  "mcpServers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Why uvx? uvx automatically downloads and runs the package on-demand — no manual installation needed. It creates an ephemeral environment, fetches from PyPI, and runs it all in one step.

Option B: Local Development (From Source)

For contributing or running from a cloned repository:

# 1. Clone the repository
git clone https://github.com/ulikoenig/mcp-atlassian-with-bitbucket.git
cd mcp-atlassian-with-bitbucket

# 2. Install dependencies with uv
uv sync --frozen --all-extras

Then add to your MCP configuration:

{
  "mcpServers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-atlassian-with-bitbucket", "mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Note: Bitbucket Cloud uses its own scoped API tokens, separate from your Jira/Confluence Atlassian API token — see Bitbucket Cloud below for how to create one.

Autohand Code

Use the same uvx server with your Atlassian credentials:

autohand mcp add mcp-atlassian-with-bitbucket-and-privacy env \
  JIRA_URL=https://your-company.atlassian.net \
  JIRA_USERNAME=your.email@company.com \
  JIRA_API_TOKEN=your_api_token \
  CONFLUENCE_URL=https://your-company.atlassian.net/wiki \
  CONFLUENCE_USERNAME=your.email@company.com \
  CONFLUENCE_API_TOKEN=your_api_token \
  uvx mcp-atlassian-with-bitbucket-and-privacy

Add --scope project after add to keep the configuration in the current project. See Autohand Code for current installation and CLI details.

Start Using

Ask your AI assistant to:

• "Find issues assigned to me in PROJ project" (Jira)
• "Search Confluence for onboarding docs" (Confluence)
• "List open PRs in the backend repo" (Bitbucket)
• "Show the diff for PR #42" (Bitbucket)
• "Approve PR #42 and add a comment" (Bitbucket)
• "Trigger a pipeline on the main branch" (Bitbucket Cloud)

Compatibility

Authentication

Jira & Confluence (Cloud)

How to get your API token:

1. Go to id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a label (e.g., "MCP Server") and click Create
4. Copy the token immediately — it won't be shown again

JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com        # Your Atlassian account email
JIRA_API_TOKEN=ATATT3x...                   # Token from step above

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com   # Same email as Jira
CONFLUENCE_API_TOKEN=ATATT3x...              # Same token works for both

Tip: One Atlassian API token works for both Jira and Confluence — you don't need separate tokens.

Jira & Confluence (Server/DC)

Create a Personal Access Token from your Jira/Confluence profile settings.

JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=your_pat

CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=your_pat

Bitbucket Cloud

Two authentication methods are supported. Bitbucket API Token is recommended — it supports granular scopes so you only grant the permissions you need.

Option A: Bitbucket API Token (Recommended)

Bitbucket now has its own scoped API tokens, separate from Atlassian API tokens. This lets you grant only Bitbucket-specific permissions.

How to create a Bitbucket API token with scopes:

1. Go to bitbucket.org and click your avatar → Personal settings
2. Under Security, select Create and manage API tokens
3. Click Create API token with scopes
4. Name the token (e.g., "MCP Server")
5. Set an expiry date (or leave blank for no expiry)
6. Select Bitbucket as the app
7. Select the scopes below based on which toolsets you plan to use:

Minimum scopes for read-only PR monitoring: Repositories: Read + Pull requests: Read

8. Click Create and copy the token — it's only shown once

BITBUCKET_URL=https://bitbucket.org
BITBUCKET_USERNAME=your.email@company.com    # Your Atlassian account email
BITBUCKET_API_TOKEN=bb_pat_xxxxxxxxxxxx      # Bitbucket API token from step above
BITBUCKET_WORKSPACE=your_workspace           # Your workspace slug (from URL: bitbucket.org/{workspace})

Option B: App Password (Deprecated)

Warning: Bitbucket is deprecating app passwords. New app passwords cannot be created after September 9, 2025, and existing ones stop working on June 9, 2026. Migrate to API tokens (Option A).

Create an App Password with these permissions:

• Repositories: Read, Write
• Pull requests: Read, Write
• Pipelines: Read, Write (if using pipeline tools)
• Webhooks: Read, Write (if using webhook tools)

BITBUCKET_URL=https://bitbucket.org
BITBUCKET_USERNAME=your_username             # Your Bitbucket username (not email)
BITBUCKET_APP_PASSWORD=your_app_password     # App password from step above
BITBUCKET_WORKSPACE=your_workspace

Note: When using an API token, set BITBUCKET_API_TOKEN. When using an app password, set BITBUCKET_APP_PASSWORD. Both use the same username + secret authentication under the hood.

Bitbucket Server/Data Center

Create a Personal Access Token with Project Read and Repository Admin permissions.

BITBUCKET_URL=https://bitbucket.your-company.com
BITBUCKET_PERSONAL_TOKEN=your_pat
BITBUCKET_PROJECT_KEY=PROJ

Finding Your Workspace Slug

Your workspace slug is the part after bitbucket.org/ in your repository URLs:

https://bitbucket.org/my-company/my-repo
                      ^^^^^^^^^^
                      This is your workspace slug

You can also find it at: bitbucket.org/account/workspaces

Configuration Reference

Bitbucket Environment Variables

Global Settings

Structured Identity Privacy (Opt-in)

Structured user identities in Jira, Confluence, and Bitbucket responses can be anonymized or time-bounded pseudonymized at the final MCP response boundary. The public default is off, so existing deployments and response shapes remain unchanged until the feature is explicitly enabled.

See Structured Identity Privacy for policy syntax, Docker and Kubernetes/Helm examples, failure behavior, and scope limitations.

Toolset Reference

Tools are organized into 37 toolsets controlled via the TOOLSETS env var. Default toolsets are enabled when TOOLSETS=default.

Bitbucket Toolsets (12)

Jira Toolsets (16)

Confluence Toolsets (8)

Additionally, a legacy toolset (off by default) retains deprecated tools kept for migration compatibility — it isn't tied to a single product.

Toolset Configuration Examples

# All tools (default when TOOLSETS is unset)
TOOLSETS=all

# Only default toolsets (11 toolsets: 4 Jira + 2 Confluence + 5 Bitbucket)
TOOLSETS=default

# Defaults + pipelines and agile
TOOLSETS=default,bitbucket_pipelines,jira_agile

# Only Bitbucket tools
TOOLSETS=bitbucket_repositories,bitbucket_pull_requests,bitbucket_branches,bitbucket_commits,bitbucket_source

# Only Jira and Confluence (no Bitbucket)
TOOLSETS=jira_issues,jira_fields,jira_comments,jira_transitions,confluence_pages,confluence_comments

Bitbucket Tool Catalog (64 tools)

Client Setup Guides

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Claude Code

The recommended approach is to add the server directly in ~/.claude/settings.json (user-level) so environment variables are bundled with the config:

{
  "mcpServers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

For local development (running from source instead of published package):

{
  "mcpServers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-atlassian-with-bitbucket-and-privacy", "mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Note: The claude mcp add CLI command works too, but doesn't support inline env — you'd need to export variables in your shell profile instead.

Cursor

Add to .cursor/mcp.json (uses the mcpServers key, same format as Claude Desktop):

{
  "mcpServers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json (uses the servers key, not mcpServers):

{
  "servers": {
    "mcp-atlassian-with-bitbucket-and-privacy": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket-and-privacy"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Architecture

src/mcp_atlassian_with_bitbucket_and_privacy/
├── bitbucket/
│   ├── config.py          # BitbucketConfig with Cloud/Server detection
│   └── client.py          # Unified client with dual Cloud/Server API support
├── jira/                   # Jira client (existing)
├── confluence/             # Confluence client (existing)
├── servers/
│   ├── main.py            # Main MCP server mounting all sub-servers
│   ├── jira.py            # 63 Jira tool definitions
│   ├── confluence.py      # 35 Confluence tool definitions
│   └── bitbucket.py       # 64 Bitbucket tool definitions
└── utils/
    ├── toolsets.py         # 37 toolset definitions and filtering
    └── tools.py            # Tool-level filtering utilities

Key Design Decisions

• Unified client: Single BitbucketClient handles both Cloud (API 2.0) and Server/DC (API 1.0) with automatic detection
• Retry middleware: Exponential backoff (3 attempts) for 429 rate limits and 5xx server errors, with Retry-After header support
• Connection pooling: httpx with 20 max connections, 10 keepalive, 30s expiry
• Cloud-only guard: Pipeline and deployment tools raise clear errors on Server/DC instead of silently failing
• Toolset filtering: Tag-based system lets users enable only the tools they need

Troubleshooting

LLM Context Optimization

This fork includes features to reduce LLM context usage when working with large responses:

Compact PR Details

Use compact: true when calling get_pull_request to return only essential fields instead of the full API response. Reduces output size by ~90%.

Essential fields returned:

• id, title, state, description
• author (display name only)
• source / destination (each with branch, repo, commit)
• reviewers (list of display names), approved_by (list of display names who approved)
• created_on, updated_on, comment_count, task_count
• merge_commit, close_source_branch, draft, links.html

Example usage in your AI assistant:

"Get PR #42 details in compact mode"

Save Diff to File

Use save_to_file: true when calling get_pull_request_diff to write the diff to a file in the system temp directory instead of returning the raw text (e.g. /tmp/bitbucket.diff on Linux/macOS, %TEMP%\bitbucket.diff on Windows). Returns a metadata object with:

{
  "file_path": "/tmp/bitbucket.diff",
  "size_bytes": 125432,
  "line_count": 2847,
  "hint": "Use a file-read tool to view the diff content"
}

This prevents large diffs from flooding the LLM context window. Read the file separately when needed.

Example usage in your AI assistant:

"Get the diff for PR #42 and save it to a file"

Security

Never share API tokens, app passwords, pseudonym keys, or private identity policies. Keep .env and mounted secret files secure and out of version control. See SECURITY.md and Structured Identity Privacy.

Contributing

See CONTRIBUTING.md for development setup.

License

MIT - See LICENSE. Not an official Atlassian product.