Bitbucket MCP server

What it does

This server lets an agent browse Bitbucket Cloud repositories, read and open pull requests, comment on them, read issues and commits, and read or start Pipelines runs. It is bitbucket-mcp-server, an ISC-licensed community package from WilliamLINWEN/bitbucket-mcp, and Atlassian does not maintain it. Statio runs version 3.2.0 with your Atlassian email and an API token. It talks only to api.bitbucket.org, so Bitbucket Data Center and Server are not covered.

Tools

Version 3.2.0 lists 17 tools. None of them set annotations, so the last column comes from what each tool calls in the package source. There is no tool that merges, approves or declines a pull request, deletes a branch, or changes an issue.

search is lighter than its name. It reads the first 100 repositories in the workspace and makes one list call per repository for pull requests and issues, then filters by substring. It does not search code, and repositories past the first 100 are skipped.

Set it up

Both setups need an API token. In Bitbucket, select your profile, then Account settings, the Security tab, Create and manage API tokens and Create API token with scopes. Give it a name and an expiry date, pick Bitbucket as the app, and choose scopes. Copy the token when it appears.

Scopes are where the real limit lives, because Bitbucket refuses any call the token isn't scoped for, whatever your MCP client allows. For an agent that only reads:

• read:repository:bitbucket for repositories, branches, commits and search
• read:pullrequest:bitbucket for pull requests, diffs and comments
• read:issue:bitbucket for issues
• read:pipeline:bitbucket for runs, steps and logs
• read:workspace:bitbucket and read:user:bitbucket for the workspace and the health check

Add write:pullrequest:bitbucket only for an agent that should open pull requests or comment, and write:pipeline:bitbucket only for one that should start runs. Atlassian's docs say write:pullrequest:bitbucket also allows approving, declining and merging. This server has no tool for those, but the token can still do them for anything else that holds it. API tokens are the replacement for app passwords, and the server still accepts an app password if you set BITBUCKET_APP_PASSWORD instead.

The server signs in with your Atlassian account email and the token. A workspace or project access token also works on its own, without the email, and keeps the agent off your personal account.

Claude Code, directly:

claude mcp add bitbucket \
  -e BITBUCKET_USERNAME=you@your-company.com \
  -e BITBUCKET_API_TOKEN=your-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y -p bitbucket-mcp-server@3.2.0 bitbucket-mcp

The package ships two binaries, the server and a bb CLI, so -p and the bin name are both needed.

Cursor, directly, in ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "-p", "bitbucket-mcp-server@3.2.0", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "you@your-company.com",
        "BITBUCKET_API_TOKEN": "${env:BITBUCKET_API_TOKEN}",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

BITBUCKET_WORKSPACE is only a default for calls that don't name one. It doesn't stop a call from naming another workspace the token can reach.

The client tutorials, How to add MCP servers to Claude Code and How to set up MCP servers in Cursor, explain config scopes and how to keep the token out of files you commit.

Through Statio: install Bitbucket from the catalog, paste the email, token and default workspace under the server's Credentials, and grant tools under Permissions. A new server has no grants, so nobody can call it until you add some. The desktop app then writes your client configs. The manual entry is the local proxy URL with the server name from your dashboard, http://127.0.0.1:7777/bitbucket/mcp, added in Claude Code with claude mcp add --transport http bitbucket <url> or as a "url" in Cursor. Tools missing after that? Start a fresh session, then work through How to debug an MCP server that won't connect.

What to hold back

The missing tools help here. With no merge, approve or delete in the server, the worst an agent can do through it is open, comment and start runs. Each of those still lands under the token owner's name.

trigger-pipeline is the tool to think hardest about. With a selector it can start any custom pipeline in bitbucket-pipelines.yml, and in many repositories that includes the deploy. It also passes whatever variables the agent chooses into the run. Keep it, and the write:pipeline:bitbucket scope, away from any agent that isn't meant to deploy. An agent that reports on failed builds needs pipelines and pipeline-steps, which only read.

create-pr-comment and create-pull-request act in front of people. Reviewers you add are notified, and comments appear as yours on someone else's work. update-pr-description replaces the description a reviewer may already be reading, with no tool to see the old text. A coding agent that opens its own pull requests can reasonably have create-pull-request and create-pr-comment. Hold back resolve-pr-comment from it, since closing review threads on its own pull request is how feedback gets lost.

Pull request descriptions, comments, commit messages, issues and pipeline logs are text written by other people, and any of it can carry instructions aimed at the agent. An agent that reads diffs and comments and also holds trigger-pipeline is the setup where that text can start a deploy.

A personal API token reaches every repository you can, in every workspace you belong to, up to its scopes. A workspace or project access token narrows that to one workspace or project, which is usually the better fit for a shared agent.

With Statio you grant each tool separately, so a review agent can read diffs and post comments while a build agent reads pipelines and nothing else. MCP permissions covers how grants and denies combine, and How to give an AI agent read-only GitHub access walks through the same read-only approach on GitHub.

Questions