Merge Unified's Bitbucket integration Merge Agent Handler's Bitbucket MCP server

Connect your AI Agents to Bitbucket in minutes

Merge lets you securely connect your agents to Bitbucket and thousands of tools instantly

Start building for free

Read docs

Bitbucket

Learn more about Merge Agent Handler

Available tools

list_branches

List repository branches

get_branch

Get branch details by name

create_branch

Create a new branch

delete_branch

Delete a branch

get_default_branch

Get repository default branch

list_commits

List repository commits with filters

get_commit

Get commit details by hash

get_commit_diff

Get commit diff

approve_commit

Approve a commit

unapprove_commit

Remove commit approval

list_commit_statuses

List commit build statuses

list_commit_comments

List commit comments

list_pipelines

List repository pipelines

get_pipeline

Get pipeline details by UUID

trigger_pipeline

Trigger a new pipeline run

stop_pipeline

Stop a running pipeline

list_pipeline_steps

List pipeline steps

get_pipeline_step

Get pipeline step details

get_pipeline_step_log

Get pipeline step logs

list_pipeline_variables

List pipeline variables

list_pullrequests

List pull requests with filtering options

get_pullrequest

Get pull request details by ID

create_pullrequest

Create a new pull request

update_pullrequest

Update pull request details

merge_pullrequest

Merge a pull request

decline_pullrequest

Decline a pull request

approve_pullrequest

Approve a pull request

unapprove_pullrequest

Remove approval from a pull request

list_pullrequest_comments

List pull request comments

create_pullrequest_comment

Add a comment to a pull request

list_pullrequest_commits

List pull request commits

get_pullrequest_diff

Get pull request diff

list_pullrequest_statuses

List pull request build statuses

get_pullrequest_activity

Get pull request activity log

request_pullrequest_changes

Request changes on a pull request

list_repositories

List repositories in a workspace with pagination

get_repository

Get repository details by slug

create_repository

Create a new repository in a workspace

update_repository

Update repository settings

delete_repository

Delete repository permanently

list_repository_forks

List repository forks

fork_repository

Fork a repository

list_repository_watchers

List repository watchers

get_current_user

Get authenticated user profile

list_user_emails

List user email addresses

list_workspaces

List accessible workspaces

get_workspace

Get workspace details

list_workspace_members

List workspace members

validate_credential

Validate Bitbucket credentials. Verifies credentials during setup.

list_webhooks

List repository webhooks

get_webhook

Get webhook details by UUID

create_webhook

Create a repository webhook

update_webhook

Update webhook configuration

delete_webhook

Delete webhook permanently

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Bitbucket MCP server

What is a Bitbucket MCP?

It's an MCP server that lets your agents interact with Bitbucket via tools. Your agents can invoke these tools to create and manage repositories, open and merge pull requests, trigger and monitor pipelines, manage branches, and more.

Bitbucket offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Bitbucket MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Automated PR creation from tickets: When a Jira ticket moves to "Ready for Review," an agent calls <code class="blog_inline-code">create_pullrequest</code> to open a corresponding PR in the linked Bitbucket repository, pre-populated with the ticket title, branch name, and description

Pipeline failure response: When a pipeline fails, an agent calls <code class="blog_inline-code">get_pipeline_step_log</code> to retrieve the error output, posts a structured alert to the team's Slack channel with the relevant log lines, and calls <code class="blog_inline-code">trigger_pipeline</code> to retry if the failure matches a known transient pattern

Branch hygiene reporting: On a weekly schedule, an agent calls <code class="blog_inline-code">list_branches</code> to identify branches without recent commits, cross-references open pull requests to avoid flagging active work, and posts a stale branch report for the team to review and clean up

Release branch coordination: When a sprint closes, an agent calls <code class="blog_inline-code">create_branch</code> to cut a release branch from main, calls <code class="blog_inline-code">trigger_pipeline</code> to kick off the build, and posts a pipeline status update to the team channel once the run completes

What are popular tools for Bitbucket's MCP server?

Here are some of the most commonly used tools:

<code class="blog_inline-code">list_pullrequests</code> retrieves all pull requests in a repository, filterable by state such as open, merged, or declined. Good for agents that need to audit review status or generate a summary of pending work before taking an action

<code class="blog_inline-code">create_pullrequest</code> opens a new pull request from a source branch to a target branch with a specified title and description. Use this when an agent needs to initiate code review in response to an event in another system, like a completed ticket or a passing test suite

<code class="blog_inline-code">merge_pullrequest</code> merges an approved pull request into the target branch. Call this when an agent is automating a release or promotion workflow and needs to advance code after all review conditions are met

<code class="blog_inline-code">trigger_pipeline</code> kicks off a Bitbucket pipeline for a specified branch or commit. Useful for agents that need to run a build or deployment in response to an external trigger, like a scheduled release or a merge event in a dependent repository

<code class="blog_inline-code">get_pipeline_step_log</code> retrieves the log output for a specific step in a pipeline run. Call this when an agent needs to diagnose a failure, extract build artifacts, or surface error details for a downstream alert

<code class="blog_inline-code">create_branch</code> creates a new branch in a repository from a specified source commit or branch. Helpful when an agent needs to automate branch provisioning as part of a release, feature, or hotfix workflow

What makes Merge Agent Handler's Bitbucket MCP server better than alternative Bitbucket MCP servers?

Several things set Merge Agent Handler's Bitbucket MCP server apart from building your own or using a standalone alternative:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Bitbucket, this means you can prevent pipeline logs containing secrets, source code diffs, and PR descriptions from being exposed even when the agent has broad read access to your repositories

Managed authentication and credentials: Merge stores and refreshes Bitbucket credentials on your behalf. You never expose API tokens to an agent or handle re-authentication when credentials rotate across workspaces

Real-time observability and audit trail: Every tool call made against Bitbucket is logged with timestamp, tool name, input parameters, and response metadata. You can audit exactly what an agent triggered, merged, or read without adding any custom logging to your pipeline

Tool Packs and controlled access: Tool Packs let you bundle specific Bitbucket tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Bitbucket MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Bitbucket connector. Choose which tools to include: enable read tools like <code class="blog_inline-code">list_pullrequests</code> and <code class="blog_inline-code">list_pipelines</code> for monitoring use cases, or add write tools like <code class="blog_inline-code">create_pullrequest</code> and <code class="blog_inline-code">trigger_pipeline</code> if your agent needs to open PRs or run builds.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Bitbucket by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Bitbucket tools are now accessible through that endpoint.