Connect your AI Agents to Bitbucket in minutes

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.