Bitbucket MCP Server - Documentation

Full Bitbucket Cloud coverage

Everything you need to interact with Bitbucket through AI assistants

Repositories

Create, list, update, and delete repositories. Manage forks and access files.

Pull Requests

Full PR lifecycle: create, review, comment, approve, and merge.

Issues

Create and manage issues with priorities, assignees, and states.

Pipelines

Trigger, monitor, and control CI/CD pipeline runs.

Code Search

Search across all repositories in your workspace.

OAuth 2.0

Secure auth with automatic token refresh.

Installation

Install the package globally or use npx to run it directly

Terminal

# Using npm
npm install -g @lexmata/bitbucket-mcp

# Using pnpm
pnpm add -g @lexmata/bitbucket-mcp

# Or run directly with npx
npx @lexmata/bitbucket-mcp

Configuration

Choose your preferred authentication method

1

OAuth 2.0

Recommended

1. Create an OAuth consumer in your workspace settings
2. Set callback URL to http://localhost:9876/callback
3. Run the OAuth flow script to get tokens

node scripts/oauth-flow.js "CLIENT_ID" "CLIENT_SECRET"

2

App Password

Simple

1. Go to Personal Settings → App passwords
2. Create a new app password with required permissions
3. Use your username and the app password

              BITBUCKET_USERNAME=your-username
BITBUCKET_ACCESS_TOKEN=app-password
            

MCP Configuration

Add to your Claude Desktop or Cursor configuration file

mcp.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@lexmata/bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_ACCESS_TOKEN": "your-app-password"
      }
    }
  }
}

Cursor ~/.cursor/mcp.json

Claude (macOS) ~/Library/.../Claude/

Claude (Linux) ~/.config/Claude/

Available Tools

25+ tools covering all major Bitbucket operations

Tool	Description
list_repositories	List repositories in a workspace
get_repository	Get details of a specific repository
create_repository	Create a new repository
delete_repository	Delete a repository
list_repository_forks	List all forks of a repository
get_file_content	Get the content of a file

Tool	Description
list_pull_requests	List pull requests with optional filtering
get_pull_request	Get details of a specific pull request
create_pull_request	Create a new pull request
update_pull_request	Update a pull request
merge_pull_request	Merge a pull request
decline_pull_request	Decline a pull request
approve_pull_request	Approve a pull request
request_changes	Request changes on a pull request
list_pr_comments	List comments on a pull request
add_pr_comment	Add a comment to a pull request
get_pr_diff	Get the diff for a pull request

Tool	Description
list_branches	List branches in a repository
get_branch	Get details of a specific branch
create_branch	Create a new branch
delete_branch	Delete a branch

Tool	Description
list_commits	List commits with optional filtering
get_commit	Get details of a specific commit
get_commit_diff	Get the diff for a commit

Tool	Description
list_issues	List issues in a repository
get_issue	Get details of a specific issue
create_issue	Create a new issue
update_issue	Update an issue
delete_issue	Delete an issue

Tool	Description
list_pipelines	List pipeline runs
get_pipeline	Get details of a pipeline run
trigger_pipeline	Trigger a new pipeline run
stop_pipeline	Stop a running pipeline
search_code	Search code across repositories

MCP Resources

Access Bitbucket data through standardized resource URIs

Repository

bitbucket://repository/{workspace}/{repo}

Pull Request

bitbucket://pullrequest/{workspace}/{repo}/{id}

File

bitbucket://file/{workspace}/{repo}/{path}