mcp-bitbucket

An MCP server (stdio) for the Bitbucket Cloud REST API 2.0. Works with Cursor: pull requests, pipelines, logs, clone.

The tools are consistent with the typical bb_get / bb_post / bb_put / bb_patch / bb_delete / bb_clone set.

Requirements

• Node.js 18+

• Scoped Atlassian API Token (App Passwords don't work)

Token: id.atlassian.com → API tokens.
Useful scopes: repository, pull request, pipeline, and user read (read:repository:bitbucket, read:pullrequest:bitbucket, read:pipeline:bitbucket, read:user:bitbucket). For write, add the corresponding write:*.

Related MCP server: bitbucket-mcp

Installation

git clone https://github.com/genkis/mcp-bitbucket.git
cd mcp-bitbucket
npm install

Copy .env.example to .env and fill in the values locally. Do not commit the .env file.

Cursor (~/.cursor/mcp.json)

Keep the token and email only in the local Cursor configuration, not in this repository.

{
  "mcpServers": {
    "bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/index.js"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "your-scoped-api-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

After making changes, reload the MCP servers in Cursor.

Variables:

Aliases: BITBUCKET_USERNAME, BITBUCKET_API_TOKEN.

Tools

The /2.0 prefix is added automatically. The path starts with /, e.g. /workspaces.

Common parameters: path, optionally queryParams, jq (JMESPath), outputFormat (toon or json). bb_post / bb_put / bb_patch require body.

Example paths:

• /workspaces

• /repositories/{workspace}/{repo}/pullrequests/{id}

• /repositories/{workspace}/{repo}/pullrequests/{id}/diff

• /repositories/{workspace}/{repo}/pipelines/?pagelen=50&sort=-created_on

• /repositories/{workspace}/{repo}/pipelines/{uuid}/steps/{stepUuid}/log

It's worth applying the jq filter whenever dealing with lists, to avoid pulling the entire JSON into the model.

Security

• Do not commit tokens, .env, or mcp.json with secrets.

• This server only forwards requests to api.bitbucket.org with Basic Auth (email + token).

• Logs and errors do not print the token.