MCP Atlassian + Bitbucket

MCP Atlassian + Bitbucket

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

136 tools across 33 toolsets: 49 Jira + 23 Confluence + 64 Bitbucket.

Fork of sooperset/mcp-atlassian with comprehensive Bitbucket Cloud and Server/DC integration.

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": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "[email protected]",
        "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/jellythomas/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": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-atlassian-with-bitbucket", "mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "[email protected]",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

Tip: If you already have Jira/Confluence API tokens, the same token works for Bitbucket Cloud — no need to create a separate app password.

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
[email protected]        # Your Atlassian account email
JIRA_API_TOKEN=ATATT3x...                   # Token from step above

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
[email protected]   # 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
[email protected]    # 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

Toolset Reference

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

Bitbucket Toolsets (12)

Jira Toolsets (15)

Confluence Toolsets (6)

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": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket"],
      "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": {
      "command": "uvx",
      "args": ["mcp-atlassian-with-bitbucket"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "[email protected]",
        "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": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-atlassian-with-bitbucket", "mcp-atlassian"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_USERNAME": "[email protected]",
        "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 / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

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

Architecture

src/mcp_atlassian/
├── 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            # 49 Jira tool definitions
│   ├── confluence.py      # 23 Confluence tool definitions
│   └── bitbucket.py       # 64 Bitbucket tool definitions
└── utils/
    ├── toolsets.py         # 33 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, account ID)
• source_branch, destination_branch
• reviewers (list with names and approval status)
• created_on, updated_on

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 temporary file (/tmp/bitbucket.diff) instead of returning the raw text. 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 or app passwords. Keep .env files secure and out of version control. See SECURITY.md.

Contributing

See CONTRIBUTING.md for development setup.

License

MIT - See LICENSE. Not an official Atlassian product.