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.