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": "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/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": "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"
      }
    }
  }
}

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

| Product | Deployment | Support | |---------|------------|---------| | Jira | Cloud | Fully supported | | Jira | Server/Data Center | Supported (v8.14+) | | Confluence | Cloud | Fully supported | | Confluence | Server/Data Center | Supported (v6.0+) | | Bitbucket | Cloud | Fully supported | | Bitbucket | Server/Data Center | Supported (v7.0+) |

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:

| Scope | Required for | Toolset | |-------|-------------|---------| | Repositories: Read | Browsing repos, source code, file content | bitbucket_repositories, bitbucket_source | | Repositories: Write | Creating/updating repos, forks | bitbucket_repositories | | Pull requests: Read | Listing and viewing PRs, diffs, comments | bitbucket_pull_requests | | Pull requests: Write | Creating, approving, merging PRs, comments | bitbucket_pull_requests | | Webhooks: Read | Listing webhooks | bitbucket_webhooks | | Webhooks: Write | Creating/updating webhooks | bitbucket_webhooks | | Pipelines: Read | Viewing pipeline runs, logs, variables | bitbucket_pipelines | | Pipelines: Write | Triggering/stopping pipelines | bitbucket_pipelines | | Projects: Read | Viewing project details | bitbucket_workspace | | Workspace membership: Read | Listing workspace members | bitbucket_workspace |

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

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BITBUCKET_URL | Yes | — | https://bitbucket.org (Cloud) or your Server URL | | BITBUCKET_USERNAME | Cloud | — | Bitbucket username (email for API token, username for app password) | | BITBUCKET_APP_PASSWORD | Cloud | — | App password (Cloud) | | BITBUCKET_API_TOKEN | Cloud | — | API token (Cloud) — alternative to app password, reusable from Jira/Confluence | | BITBUCKET_PERSONAL_TOKEN | Server | — | Personal Access Token (Server/DC) | | BITBUCKET_WORKSPACE | No | — | Default workspace slug (Cloud) | | BITBUCKET_PROJECT_KEY | No | — | Default project key (Server/DC) | | BITBUCKET_SSL_VERIFY | No | true | SSL certificate verification | | BITBUCKET_TIMEOUT | No | 75 | Request timeout in seconds |

Global Settings

| Variable | Default | Description | |----------|---------|-------------| | TOOLSETS | all | Comma-separated toolsets to enable (see Toolset Reference) | | READ_ONLY_MODE | false | Block all write operations | | MCP_VERBOSE | false | Enable verbose logging |

Toolset Reference

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

Bitbucket Toolsets (12)

| Toolset | Tools | Default | Description | |---------|------:|---------|-------------| | bitbucket_repositories | 7 | Yes | Repository CRUD, search, fork | | bitbucket_pull_requests | 15 | Yes | PR lifecycle, review, merge, diff, comments | | bitbucket_branches | 5 | Yes | Branch management, branching model, restrictions | | bitbucket_commits | 6 | Yes | Commit history, compare, statuses, comments | | bitbucket_source | 5 | Yes | File browsing, code search, blame, history | | bitbucket_tags | 3 | No | Tag listing, creation, deletion | | bitbucket_webhooks | 4 | No | Webhook CRUD and event management | | bitbucket_pipelines | 8 | No | CI/CD pipelines (Cloud only) | | bitbucket_deployments | 3 | No | Deployment environments (Cloud only) | | bitbucket_downloads | — | No | Repository downloads (placeholder) | | bitbucket_snippets | — | No | Code snippets (placeholder) | | bitbucket_workspace | 5 | No | Workspace/project members, default reviewers |

Jira Toolsets (15)

| Toolset | Default | Description | |---------|---------|-------------| | jira_issues | Yes | Core issue CRUD, search, batch, changelogs | | jira_fields | Yes | Field search and options | | jira_comments | Yes | Issue comments | | jira_transitions | Yes | Workflow transitions | | jira_projects | No | Project, version, component management | | jira_agile | No | Boards, sprints, backlog | | jira_links | No | Issue links, epic links, remote links | | jira_worklog | No | Time tracking | | jira_attachments | No | Attachments and images | | jira_users | No | User profiles | | jira_watchers | No | Issue watchers | | jira_service_desk | No | JSM queues and service desks | | jira_forms | No | ProForma forms | | jira_metrics | No | Issue dates and SLA metrics | | jira_development | No | Dev info (branches, PRs, commits) |

Confluence Toolsets (6)

| Toolset | Default | Description | |---------|---------|-------------| | confluence_pages | Yes | Page CRUD, search, children, history | | confluence_comments | Yes | Page comments | | confluence_labels | No | Page labels | | confluence_users | No | User search | | confluence_analytics | No | Page view analytics | | confluence_attachments | No | Attachment management |

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": "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": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-atlassian-with-bitbucket", "mcp-atlassian"],
      "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 / 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

| Issue | Solution | |-------|----------| | Missing BITBUCKET_URL | Set BITBUCKET_URL env var | | 401 Unauthorized (Cloud) | Verify app password/API token has correct permissions. If using API token, ensure BITBUCKET_API_TOKEN is set (not BITBUCKET_APP_PASSWORD) | | 401 Unauthorized (Server) | Check PAT hasn't expired | | Pipeline tools error on Server | Pipelines are Cloud-only; use TOOLSETS to disable | | 429 Too Many Requests | Built-in retry handles this; increase BITBUCKET_TIMEOUT if persistent | | SSL errors (Server/DC) | Set BITBUCKET_SSL_VERIFY=false for self-signed certs | | Server name shows old name in /mcp | The name shown is the JSON key in your config, not the package name. Rename the key (e.g., "mcp-atlassian" → "mcp-atlassian-with-bitbucket") and restart | | Bitbucket tools not appearing | Ensure BITBUCKET_URL and credentials are set. The server auto-detects available services based on which env vars are present |

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.