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