Which integrations are available for this server?

Provides a comprehensive suite of tools for interacting with Atlassian's core products, including Jira, Confluence, and Bitbucket, with support for both Cloud and Server/Data Center deployments. Enables programmatic interaction with Bitbucket to manage repositories, source code, pull requests, and pipelines, including viewing diffs and approving comments. Allows for searching and managing Confluence documentation and content across both Cloud and Server/Data Center environments. Provides capabilities to find, create, and manage issues and projects within Jira Cloud and Server/Data Center instances.

How do I use MCP Atlassian + Bitbucket?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Atlassian + Bitbucket list my open pull requests in the backend repository" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Atlassian + Bitbucket

Python License

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:

Go to id.atlassian.com/manage-profile/security/api-tokens
Click Create API token
Give it a label (e.g., "MCP Server") and click Create
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:

Go to bitbucket.org and click your avatar → Personal settings
Under Security, select Create and manage API tokens
Click Create API token with scopes
Name the token (e.g., "MCP Server")
Set an expiry date (or leave blank for no expiry)
Select Bitbucket as the app
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

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)

Tool	Type	Description
`list_repositories`	read	List repositories in a workspace/project
`get_repository`	read	Get repository details
`create_repository`	write	Create a new repository
`update_repository`	write	Update repository settings
`delete_repository`	write	Delete a repository
`fork_repository`	write	Fork a repository
`list_forks`	read	List forks of a repository

Tool	Type	Description
`list_pull_requests`	read	List PRs with filtering (state, author, reviewer, branch)
`get_pull_request`	read	Get PR details
`get_pull_request_diff`	read	Get PR diff (paginated)
`create_pull_request`	write	Create a new PR
`update_pull_request`	write	Update PR title, description, reviewers
`merge_pull_request`	write	Merge a PR
`decline_pull_request`	write	Decline/close a PR
`approve_pull_request`	write	Approve a PR
`unapprove_pull_request`	write	Remove approval from a PR
`request_changes_pull_request`	write	Request changes on a PR
`get_pull_request_commits`	read	List commits in a PR
`add_pull_request_comment`	write	Add a general comment
`list_pull_request_comments`	read	List all PR comments
`list_pull_request_statuses`	read	List PR build statuses
`add_inline_comment`	write	Add inline comment on a specific line

Tool	Type	Description
`reply_to_comment`	write	Reply to an existing comment
`update_comment`	write	Update a comment
`delete_comment`	write	Delete a comment

Tool	Type	Description
`list_branches`	read	List branches with filtering
`create_branch`	write	Create a new branch
`delete_branch`	write	Delete a branch
`get_branching_model`	read	Get branching model configuration
`list_branch_restrictions`	read	List branch restrictions

Tool	Type	Description
`list_commits`	read	List commits with author filtering
`get_commit`	read	Get commit details
`compare_commits`	read	Compare two commits/branches
`list_commit_statuses`	read	List build statuses for a commit
`create_commit_status`	write	Set build status on a commit
`add_commit_comment`	write	Add a comment on a commit

Tool	Type	Description
`get_file_content`	read	Get file content with line range support
`browse_directory`	read	Browse directory listing
`search_code`	read	Search code across repository
`get_file_blame`	read	Get blame/annotate for a file
`get_file_history`	read	Get commit history for a file

Tool	Type	Description
`list_tags`	read	List repository tags
`create_tag`	write	Create a tag
`delete_tag`	write	Delete a tag

Tool	Type	Description
`list_webhooks`	read	List configured webhooks
`create_webhook`	write	Create a webhook
`update_webhook`	write	Update a webhook
`delete_webhook`	write	Delete a webhook

Tool	Type	Description
`list_pipelines`	read	List pipeline runs
`get_pipeline`	read	Get pipeline run details
`trigger_pipeline`	write	Trigger a new pipeline run
`stop_pipeline`	write	Stop a running pipeline
`get_pipeline_step_log`	read	Get step logs from a pipeline
`list_pipeline_variables`	read	List pipeline variables
`create_pipeline_variable`	write	Create a pipeline variable
`get_pipeline_config`	read	Get pipeline configuration

Tool	Type	Description
`list_environments`	read	List deployment environments
`get_deployment`	read	Get deployment details
`list_deployment_releases`	read	List releases for an environment

Tool	Type	Description
`list_workspaces`	read	List accessible workspaces (Cloud) / projects (Server)
`get_workspace`	read	Get workspace/project details
`list_workspace_members`	read	List workspace/project members
`get_default_reviewers`	read	Get default reviewers for a repository
`add_default_reviewer`	write	Add a default reviewer

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.