Model Context Protocol (MCP) server for Bitbucket Cloud and Server API integration
npm install bitbucket-mcp-vseeA 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.
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.




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...
-- Since it has been asked, in many cases we have seen - "BITBUCKET_USERNAME" is usually your email
The easiest way to use this MCP server is via NPX, which allows you to run it without installing it globally:
``bashOption 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
$3
Alternatively, you can install it globally or as part of your project:
`bash
Install globally
npm install -g bitbucket-mcpOr install in your project
npm install bitbucket-mcp
`Then run it with:
`bash
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-mcpIf installed globally (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcpIf 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-mcpIf 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
$3
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.$3
1. Log in to your Bitbucket account
2. Go to Personal Settings > App Passwords
3. Create a new app password with the following permissions:
- Repositories: Read
- Pull requests: Read, Write
- Pipelines: Read (required for pipeline operations)
4. Copy the generated password and use it as the
BITBUCKET_PASSWORD environment variableTroubleshooting
$3
If you're getting 401 authentication errors, check the following:
1. Verify your app password: Make sure you're using an App Password, not your regular Bitbucket password
1. Verify app password permissions: Your app password needs at least "Repositories: Read" permission
1. Try the API URL format: If you're still getting 401 errors, try using the direct API URL format:
`bash
BITBUCKET_URL="https://api.bitbucket.org/2.0"
`1. Test API access: Verify your credentials work by testing the Bitbucket API directly:
`bash
Test with curl (replace with your actual values)
curl -u "your-username:your-app-password" \
"https://api.bitbucket.org/2.0/repositories/your-workspace"
`$3
1. Put the Atlassian API Key in the
BITBUCKET_PASSWORD variable, not BITBUCKET_TOKEN
2. Use your Bitbucket email as BITBUCKET_USERNAME instead of your regular usernameFor reference you can check the API token documentation
$3
If you encounter issues:
1. Check the Bitbucket REST API documentation for API details
2. Review the Bitbucket Cloud documentation for general help
Integration with Cursor
To integrate this MCP server with Cursor:
1. Open Cursor
2. Go to Settings > Extensions
3. Click on "Model Context Protocol"
4. Add a new MCP configuration:
`json
"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"]
}
`1. Save the configuration
2. Use the "/bitbucket" command in Cursor to access Bitbucket repositories and pull requests
$3
If you're developing locally and want to test your changes:
`json
"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:
$3
Unless noted otherwise, listing tools accept the following optional parameters:
-
pagelen: Number of items per page (Bitbucket pagelen). Defaults to 10 and is capped at 100.
- page: 1-based Bitbucket page number to fetch. When omitted, the first page is returned.
- all: When true (and page is not provided), the server automatically follows Bitbucket next links until all items are fetched or a safety cap of 1,000 entries is reached.
- limit: Deprecated alias for pagelen kept for backward compatibility.Use these knobs to page through large collections without hitting CLI truncation.
$3
####
listRepositoriesLists repositories in a workspace.
Parameters:
-
workspace (optional): Bitbucket workspace name
- name (optional): Filter repositories by partial name match
- Pagination controls described in Pagination####
getRepositoryGets details for a specific repository.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug$3
####
getPullRequestsGets pull requests for a repository.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- state (optional): Pull request state (OPEN, MERGED, DECLINED, SUPERSEDED)
- Pagination controls described in Pagination####
createPullRequestCreates a new pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- title: Pull request title
- description: Pull request description
- sourceBranch: Source branch name
- targetBranch: Target branch name
- reviewers (optional): List of reviewer usernames
- draft (optional): Whether to create the pull request as a draft####
getPullRequestGets details for a specific pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_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####
updatePullRequestUpdates a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- Pagination controls described in Pagination
- Pagination controls described in Pagination
- Various optional update parameters (title, description, etc.)####
getPullRequestActivityGets the activity log for a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
approvePullRequestApproves a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
unapprovePullRequestRemoves an approval from a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
declinePullRequestDeclines a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- message (optional): Reason for declining####
mergePullRequestMerges a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- message (optional): Merge commit message
- strategy (optional): Merge strategy (merge-commit, squash, fast-forward)####
requestChangesRequests changes on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
removeChangeRequestRemoves a change request from a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
createDraftPullRequestCreates a new draft pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- title: Pull request title
- description: Pull request description
- sourceBranch: Source branch name
- targetBranch: Target branch name
- reviewers (optional): List of reviewer usernamesNote: This is equivalent to calling
createPullRequest with draft: true.####
publishDraftPullRequestPublishes a draft pull request to make it ready for review.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
convertTodraftConverts a regular pull request to draft status.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID$3
####
getPullRequestCommentsLists comments on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
addPullRequestCommentCreates a comment on a pull request (general or inline).
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- content: Comment content in markdown format
- inline (optional): Inline comment information for commenting on specific linesInline Comment Format:
The
inline parameter allows you to create comments on specific lines of code in the pull request diff:`json
{
"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
inline parameter for a general pull request comment
- Comment on new line: Use only to parameter
- Comment on deleted line: Use only from parameter
- Comment on modified line: Use both from and to parametersUsage:
`javascript
// 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,
});
`####
getPullRequestCommentGets a specific comment on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- comment_id: Comment ID####
updatePullRequestCommentUpdates a comment on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- comment_id: Comment ID
- content: Updated comment content####
deletePullRequestCommentDeletes a comment on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- comment_id: Comment ID####
resolveCommentResolves a comment thread on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- comment_id: Comment ID####
reopenCommentReopens a resolved comment thread on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- comment_id: Comment ID$3
####
getPullRequestDiffGets the diff for a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
getPullRequestDiffStatGets the diff statistics for a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
getPullRequestPatchGets the patch for a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID$3
####
getPullRequestTasksLists tasks on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
createPullRequestTaskCreates a task on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- content: Task content
- comment (optional): Comment ID to associate with the task
- pending (optional): Whether the task is pending####
getPullRequestTaskGets a specific task on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- task_id: Task ID####
updatePullRequestTaskUpdates a task on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- task_id: Task ID
- content (optional): Updated task content
- state (optional): Updated task state####
deletePullRequestTaskDeletes a task on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID
- task_id: Task ID$3
####
getPullRequestCommitsLists commits on a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID####
getPullRequestStatusesLists commit statuses for a pull request.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pull_request_id: Pull request ID$3
####
listPipelineRunsLists pipeline runs for a repository.
Parameters:
-
workspace: Bitbucket workspace name
- repo_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 branch
- trigger_type (optional): Filter pipelines by trigger type (manual, push, pullrequest, schedule)####
getPipelineRunGets details for a specific pipeline run.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pipeline_uuid: Pipeline UUID
- Pagination controls described in Pagination####
runPipelineTriggers a new pipeline run.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- target: Pipeline target configuration (object with ref_type, ref_name, and optional commit_hash, selector_type, selector_pattern)
- variables (optional): Array of pipeline variables (objects with key, value, and optional secured fields)####
stopPipelineStops a running pipeline.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pipeline_uuid: Pipeline UUID####
getPipelineStepsLists steps for a pipeline run.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pipeline_uuid: Pipeline UUID####
getPipelineStepGets details for a specific pipeline step.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pipeline_uuid: Pipeline UUID
- step_uuid: Step UUID####
getPipelineStepLogsGets logs for a specific pipeline step.
Parameters:
-
workspace: Bitbucket workspace name
- repo_slug: Repository slug
- pipeline_uuid: Pipeline UUID
- step_uuid: Step UUIDDevelopment
$3
- Node.js 18 or higher
- npm or yarn
$3
`bash
Clone the repository
git clone https://github.com/MatanYemini/bitbucket-mcp.git
cd bitbucket-mcpInstall dependencies
npm installBuild the project
npm run buildRun 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:
1. Build the project so
dist/index.js is up to date:
`bash
npm run build
`
2. Generate the registry manifest (this reads package.json and emits registry/bitbucket-mcp.manifest.json):
`bash
npm run registry:manifest
`
3. Follow the publish-server guide
to push the manifest with smithery publish or the recommended workflow from the guide.The generated manifest captures the CLI command (
node dist/index.js`), all documented configuration options, and pointers back toThis project is licensed under the MIT License - see the LICENSE file for details.
- GitHub Repository
- npm Package
- Model Context Protocol
- Bitbucket REST API Documentation
- Bitbucket Cloud Documentation