bitbucket-tool-mcp

MCP server for Bitbucket Cloud. Gives AI assistants (Claude, Cursor, etc.) direct access to pull requests, pipelines, branches, commits, and code review workflows.

Tools

| Tool | Description | |------|-------------| | list_repositories | List repositories in a workspace | | list_branches | List branches in a repository | | get_branch | Get branch details and latest commit | | create_branch | Create a branch from a commit or branch | | delete_branch | Delete a branch | | list_pull_requests | List PRs, filterable by state | | get_pull_request | Get PR details (title, branches, author, status) | | create_pull_request | Create a new PR | | update_pull_request | Update PR title, description, or destination | | decline_pull_request | Decline (close) a PR | | get_pull_request_diff | Get raw unified diff for a PR | | get_pull_request_comments | Get all comments including inline code review | | add_pull_request_comment | Add a comment to a PR | | list_pipelines | List recent pipeline runs | | get_pipeline | Get pipeline details and steps | | get_pipeline_step_log | Get raw log output for a pipeline step | | trigger_pipeline | Trigger a pipeline on a branch or tag | | list_commits | List recent commits | | get_commit | Get commit details |

Installation

Claude Desktop / Claude Code

Add to your MCP config (~/.claude.json or Claude Desktop settings):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-tool-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-tool-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio transport works. Run the server directly:

BITBUCKET_TOKEN=your-token npx bitbucket-tool-mcp

Authentication

API Token (recommended)

Set BITBUCKET_TOKEN to a Bitbucket API token or workspace access token. The token needs read/write access to repositories, pull requests, and pipelines depending on which tools you use.

export BITBUCKET_TOKEN="your-api-token"

OAuth 2.0

For OAuth flows, set both client ID and secret. Create an OAuth consumer in your Bitbucket workspace settings under OAuth consumers.

export BITBUCKET_OAUTH_CLIENT_ID="your-client-id"
export BITBUCKET_OAUTH_CLIENT_SECRET="your-client-secret"

Configuration

| Environment variable | Required | Description | |---------------------|----------|-------------| | BITBUCKET_TOKEN | Yes* | API token for Bearer auth | | BITBUCKET_OAUTH_CLIENT_ID | Yes* | OAuth 2.0 client ID | | BITBUCKET_OAUTH_CLIENT_SECRET | Yes* | OAuth 2.0 client secret | | BITBUCKET_WORKSPACE | No | Default workspace (can also be passed per tool call) |

*One auth method required: either BITBUCKET_TOKEN or both OAuth variables.

Local Development

git clone https://github.com/riotbyte-com/bitbucket-tool.git
cd bitbucket-tool
npm install
npm run build

# Run tests
npm test

# Run with MCP Inspector for interactive testing
npx @modelcontextprotocol/inspector node packages/mcp-server/dist/index.js

License

MIT