Bitbucket MCP
A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs. This MCP server enables AI assistants like Cursor to interact with your Bitbucket repositories, pull requests, and other resources.
Safety First
This is a safe and responsible package — no DELETE operations are used, so there's no risk of data loss. Every pull request is analyzed with CodeQL to ensure the code remains secure.
Overview
Checkout out the official npm package This server implements the Model Context Protocol standard to provide AI assistants with access to Bitbucket data and operations. It includes tools for:
- Listing and retrieving repositories
- Getting repository details
- Fetching pull requests
- And more...
Installation
-- Since it has been asked, in many cases we have seen - "BITBUCKET_USERNAME" is usually your email
Using NPX (Recommended)
The easiest way to use this MCP server is via NPX, which allows you to run it without installing it globally:
# Option A (recommended): API URL + explicit workspace
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest
# Option B (legacy-compatible): web URL only; workspace is auto-extracted
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest
Manual Installation
Alternatively, you can install it globally or as part of your project:
# Install globally
npm install -g bitbucket-mcp
# Or install in your project
npm install bitbucket-mcp
Then run it with:
# If installed globally (Option A)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp
# If installed globally (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp
# If installed in your project (Option A)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp
# If installed in your project (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp
Configuration
Environment Variables
Configure the server using the following environment variables:
| Variable | Description | Required |
|---|---|---|
BITBUCKET_URL | Bitbucket API base URL. Defaults to https://api.bitbucket.org/2.0 | No |
BITBUCKET_USERNAME | Your Bitbucket username | Yes* |
BITBUCKET_PASSWORD | Your Bitbucket app password | Yes* |
BITBUCKET_TOKEN | Your Bitbucket access token (alternative to username/password) | No |
BITBUCKET_WORKSPACE | Default workspace to use. If omitted and BITBUCKET_URL contains it, auto-set | No |
BITBUCKET_ENABLE_DANGEROUS | Set to true to enable dangerous tools (e.g., deletions). Default: disabled | No |
BITBUCKET_LOG_DISABLE | Disable file logging when set to true/1 | No |
BITBUCKET_LOG_FILE | Absolute path to a specific log file | No |
BITBUCKET_LOG_DIR | Directory to store logs (defaults to OS-specific app log dir) | No |
BITBUCKET_LOG_PER_CWD | When true, nest logs under a per-working-directory subfolder | No |
Either BITBUCKET_TOKEN or both BITBUCKET_USERNAME and BITBUCKET_PASSWORD must be provided.
Creating a Bitbucket App Password
- Log in to your Bitbucket account
- Go to Personal Settings > App Passwords
- Create a new app password with the following permissions:
- Repositories: Read
- Pull requests: Read, Write
- Pipelines: Read (required for pipeline operations)
- Copy the generated password and use it as the
BITBUCKET_PASSWORDenvironment variable
Troubleshooting
401 Authentication Errors
If you're getting 401 authentication errors, check the following:
- Verify your app password: Make sure you're using an App Password, not your regular Bitbucket password
- Verify app password permissions: Your app password needs at least "Repositories: Read" permission
- Try the API URL format: If you're still getting 401 errors, try using the direct API URL format:
BITBUCKET_URL="https://api.bitbucket.org/2.0"
- Test API access: Verify your credentials work by testing the Bitbucket API directly:
# Test with curl (replace with your actual values)
curl -u "your-username:your-app-password" \
"https://api.bitbucket.org/2.0/repositories/your-workspace"
Atlassian API Key
- Put the Atlassian API Key in the
BITBUCKET_PASSWORDvariable, notBITBUCKET_TOKEN - Use your Bitbucket email as
BITBUCKET_USERNAMEinstead of your regular username
For reference you can check the API token documentation
Getting Help
If you encounter issues:
- Check the Bitbucket REST API documentation for API details
- Review the Bitbucket Cloud documentation for general help
Integration with Cursor
To integrate this MCP server with Cursor:
- Open Cursor
- Go to Settings > Extensions
- Click on "Model Context Protocol"
- Add a new MCP configuration:
"bitbucket": {
"command": "npx",
"env": {
"BITBUCKET_URL": "https://api.bitbucket.org/2.0",
"BITBUCKET_WORKSPACE": "your-workspace",
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_PASSWORD": "your-app-password"
},
"args": ["-y", "bitbucket-mcp@latest"]
}
- Save the configuration
- Use the "/bitbucket" command in Cursor to access Bitbucket repositories and pull requests
Using a Local Build with Cursor
If you're developing locally and want to test your changes:
"bitbucket-local": {
"command": "node",
"env": {
"BITBUCKET_URL": "https://api.bitbucket.org/2.0",
"BITBUCKET_WORKSPACE": "your-workspace",
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_PASSWORD": "your-app-password"
},
"args": ["/path/to/your/local/bitbucket-mcp/dist/index.js"]
}
Available Tools
This MCP server provides tools for interacting with Bitbucket repositories and pull requests. Below is a comprehensive list of the available operations:
Pagination
Unless noted otherwise, listing tools accept the following optional parameters:
pagelen: Number of items per page (Bitbucketpagelen). Defaults to 10 and is capped at 100.page: 1-based Bitbucket page number to fetch. When omitted, the first page is returned.all: Whentrue(andpageis not provided), the server automatically follows Bitbucketnextlinks until all items are fetched or a safety cap of 1,000 entries is reached.limit: Deprecated alias forpagelenkept for backward compatibility.
Use these knobs to page through large collections without hitting CLI truncation.
Repository Operations
listRepositories
Lists repositories in a workspace.
Parameters:
workspace(optional): Bitbucket workspace namename(optional): Filter repositories by partial name match- Pagination controls described in Pagination
getRepository
Gets details for a specific repository.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slug
Pull Request Operations
getPullRequests
Gets pull requests for a repository.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugstate(optional): Pull request state (OPEN,MERGED,DECLINED,SUPERSEDED)- Pagination controls described in Pagination
createPullRequest
Creates a new pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugtitle: Pull request titledescription: Pull request descriptionsourceBranch: Source branch nametargetBranch: Target branch namereviewers(optional): List of reviewer usernamesdraft(optional): Whether to create the pull request as a draft
getPullRequest
Gets details for a specific pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID- Pagination controls described in Pagination
- Pagination controls described in Pagination
- Pagination controls described in Pagination
- Pagination controls described in Pagination
updatePullRequest
Updates a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID- Pagination controls described in Pagination
- Pagination controls described in Pagination
- Various optional update parameters (title, description, etc.)
getPullRequestActivity
Gets the activity log for a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
approvePullRequest
Approves a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
unapprovePullRequest
Removes an approval from a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
declinePullRequest
Declines a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDmessage(optional): Reason for declining
mergePullRequest
Merges a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDmessage(optional): Merge commit messagestrategy(optional): Merge strategy (merge-commit,squash,fast-forward)
requestChanges
Requests changes on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
removeChangeRequest
Removes a change request from a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
createDraftPullRequest
Creates a new draft pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugtitle: Pull request titledescription: Pull request descriptionsourceBranch: Source branch nametargetBranch: Target branch namereviewers(optional): List of reviewer usernames
Note: This is equivalent to calling createPullRequest with draft: true.
publishDraftPullRequest
Publishes a draft pull request to make it ready for review.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
convertTodraft
Converts a regular pull request to draft status.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
Pull Request Comment Operations
getPullRequestComments
Lists comments on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
addPullRequestComment
Creates a comment on a pull request (general or inline).
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcontent: Comment content in markdown formatinline(optional): Inline comment information for commenting on specific lines
Inline Comment Format:
The inline parameter allows you to create comments on specific lines of code in the pull request diff:
{
"path": "src/file.ts",
"to": 15, // Line number in NEW version (for added/modified lines)
"from": 10 // Line number in OLD version (for deleted/modified lines)
}
Examples:
- General comment: Omit the
inlineparameter for a general pull request comment - Comment on new line: Use only
toparameter - Comment on deleted line: Use only
fromparameter - Comment on modified line: Use both
fromandtoparameters
Usage:
// General comment
addPullRequestComment(workspace, repo, pr_id, "Great work!");
// Inline comment on new line 25
addPullRequestComment(workspace, repo, pr_id, "Consider error handling here", {
path: "src/service.ts",
to: 25,
});
getPullRequestComment
Gets a specific comment on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcomment_id: Comment ID
updatePullRequestComment
Updates a comment on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcomment_id: Comment IDcontent: Updated comment content
deletePullRequestComment
Deletes a comment on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcomment_id: Comment ID
resolveComment
Resolves a comment thread on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcomment_id: Comment ID
reopenComment
Reopens a resolved comment thread on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcomment_id: Comment ID
Pull Request Diff Operations
getPullRequestDiff
Gets the diff for a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
getPullRequestDiffStat
Gets the diff statistics for a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
getPullRequestPatch
Gets the patch for a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
Pull Request Task Operations
getPullRequestTasks
Lists tasks on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
createPullRequestTask
Creates a task on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDcontent: Task contentcomment(optional): Comment ID to associate with the taskpending(optional): Whether the task is pending
getPullRequestTask
Gets a specific task on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDtask_id: Task ID
updatePullRequestTask
Updates a task on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDtask_id: Task IDcontent(optional): Updated task contentstate(optional): Updated task state
deletePullRequestTask
Deletes a task on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request IDtask_id: Task ID
Other Pull Request Operations
getPullRequestCommits
Lists commits on a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
getPullRequestStatuses
Lists commit statuses for a pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID
Pipeline Operations
listPipelineRuns
Lists pipeline runs for a repository.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slug- Pagination controls described in Pagination
status(optional): Filter pipelines by status (PENDING,IN_PROGRESS,SUCCESSFUL,FAILED,ERROR,STOPPED)target_branch(optional): Filter pipelines by target branchtrigger_type(optional): Filter pipelines by trigger type (manual,push,pullrequest,schedule)
getPipelineRun
Gets details for a specific pipeline run.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpipeline_uuid: Pipeline UUID- Pagination controls described in Pagination
runPipeline
Triggers a new pipeline run.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugtarget: Pipeline target configuration (object withref_type,ref_name, and optionalcommit_hash,selector_type,selector_pattern)variables(optional): Array of pipeline variables (objects withkey,value, and optionalsecuredfields)
stopPipeline
Stops a running pipeline.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpipeline_uuid: Pipeline UUID
getPipelineSteps
Lists steps for a pipeline run.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpipeline_uuid: Pipeline UUID
getPipelineStep
Gets details for a specific pipeline step.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpipeline_uuid: Pipeline UUIDstep_uuid: Step UUID
getPipelineStepLogs
Gets logs for a specific pipeline step.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpipeline_uuid: Pipeline UUIDstep_uuid: Step UUID
Development
Prerequisites
- Node.js 18 or higher
- npm or yarn
Setup
# Clone the repository
git clone https://github.com/MatanYemini/bitbucket-mcp.git
cd bitbucket-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode
npm run dev
Publishing to the MCP Registry
Use the official Model Context Protocol publishing guide when you are ready to make a new server release. The repository includes everything that guide expects:
- Build the project so
dist/index.jsis up to date:npm run build - Generate the registry manifest (this reads
package.jsonand emitsregistry/bitbucket-mcp.manifest.json):npm run registry:manifest - Follow the publish-server guide
to push the manifest with
smithery publishor the recommended workflow from the guide.
The generated manifest captures the CLI command (node dist/index.js), all documented configuration options, and pointers back to
this README for setup instructions, so it can be submitted directly to the MCP registry.
License
This project is licensed under the MIT License - see the LICENSE file for details.