bitbucket-mcp

A Model Context Protocol (MCP) server that gives AI assistants (like Claude) programmatic access to Bitbucket Cloud. It enables reading and managing pull requests, browsing repositories and branches, and automating code review workflows from your MCP client.

It authenticates with Bitbucket using an app password tied to your Atlassian account. Multiple workspace connections can be configured, with an optional default repository per workspace.

What You Can Do

• "List all open PRs in my-repo targeting the main branch"
• "Create a pull request from feature/SCC-1234 to develop with a summary of the changes"
• "Show me what files changed in PR #42 and give me a line-by-line diff of the auth module"
• "Find the PR for branch feature/payments and merge it with a squash strategy"
• "Decline the stale PRs that have been open for more than 30 days"

Features

• Multi-workspace support: configure and switch between multiple Bitbucket Cloud workspaces
• Default repository: set a default repo per workspace so you don't need to specify it every call
• Web UI: browser-based management console for adding/editing workspace connections
• Protected branches: mark branches as protected to prevent accidental AI-triggered merges
• Branch autocomplete: the UI fetches and caches branch names for fast autocomplete
• Real-time activity log: live MCP tool execution log via SSE streamed to the Web UI
• Mock OAuth: built-in OAuth stub so MCP clients that require OAuth flows work out of the box

Tools

| Tool | Description | |------|-------------| | list_workspaces | List all configured Bitbucket workspace connections | | list_repos | List repositories in a workspace | | list_branches | List branches in a repository with optional name filter | | get_pull_requests | List pull requests filtered by state, source, or destination branch | | get_pull_request | Get details of a single pull request | | create_pull_request | Open a new pull request | | merge_pull_request | Merge a pull request (merge commit, squash, or fast-forward) | | decline_pull_request | Decline a pull request | | get_pr_diff | List all files changed in a PR with line counts | | get_pr_file_diff | Get the full diff for a specific file in a PR |

Installation

Via npx (recommended)

npx @yunusemregul/bitbucket-mcp

Global install

npm install -g @yunusemregul/bitbucket-mcp
bitbucket-mcp

The server starts on http://localhost:18434 by default.

Options:
  -p, --port    Port to listen on (default: 18434)
  -v, --version Print version
  -h, --help    Show help

Workspace configuration is stored in ~/.bitbucket-mcp/workspaces.json.

Configuration

Via Web UI

Open http://localhost:18434/ in your browser, click + Add Workspace, fill in the details (connection is tested automatically as you type), then click Save.

Workspace options

| Field | Type | Description | |-------|------|-------------| | name | string | Display name for this connection | | workspaceSlug | string | Bitbucket workspace slug (from the URL) | | username | string | Atlassian account email | | token | string | Bitbucket app password | | repoSlug | string | Default repository slug (optional) | | protectedBranches | string[] | Branches the AI is not allowed to merge into |

Tip: Set protectedBranches to ["main", "master"] on production workspaces to block accidental merges.

Using with Claude

Claude Code (recommended)

claude mcp add --transport sse bitbucket-mcp http://localhost:18434/mcp/sse

Other MCP clients

{
  "mcpServers": {
    "bitbucket-mcp": {
      "url": "http://localhost:18434/mcp/sse"
    }
  }
}

Project Structure

bitbucket-mcp/
├── server.js           # Express app, MCP SSE endpoint, REST API
├── bitbucket.js        # Bitbucket Cloud API client
├── storage.js          # Workspace config persistence
├── tools/
│   ├── index.js        # Tool registry
│   ├── context.js      # Shared runtime state (sessions, logging)
│   └── *.js            # One file per MCP tool
└── static/
    ├── index.html      # Management console UI
    ├── app.js          # UI logic
    └── style.css       # Styles

Security Notes

• Credentials are stored in plaintext in ~/.bitbucket-mcp/workspaces.json. Avoid exposing this file.
• Use Bitbucket app passwords with the minimum required scopes rather than your main account password.
• Use protectedBranches to prevent the AI from merging into sensitive branches.