Bitbucket Protocol Endpoint

Introduction

This server conforms to the Model Context Protocol standard, granting AI agents like Cursor secure access to data within Bitbucket Cloud and Server environments. Managing version control effectively is central to modern software development workflows. This endpoint focuses on repository inspection and pull request manipulation, adhering to principles of secure, non-destructive access.

Safety First

This implementation upholds strong safety guarantees by design; absolutely no data deletion operations are executed, eliminating the possibility of accidental content removal. Furthermore, rigorous security checks are performed on every proposed code modification via CodeQL analysis before any further interaction proceeds.

Overview

Refer to the official npm package for the published version. This server is engineered to fulfill the MCP specification, providing assistants with structured access to Bitbucket resources. Capabilities include fetching repository listings, retrieving specific project details, examining pending pull requests, and more.

Setup

Using NPX (Recommended)

Executing the server using NPX offers the simplest deployment route, avoiding a permanent global installation on your system.

# Execute while defining necessary connection parameters
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 have the option to install the package either globally across your environment or locally within your project structure.

# Perform a global installation
npm install -g bitbucket-mcp

# Or install it as a dependency for your project
npm install bitbucket-mcp

Then initiate the server execution with:

# If installed globally
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp

# If installed locally using npx
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp

Configuration

Environment Variables

The server's behavior is governed by setting the following environment variables:

Variable	Description	Required
BITBUCKET_URL	The base address for the Bitbucket instance (e.g., "https://bitbucket.org/your-workspace")	Yes
BITBUCKET_USERNAME	The designated username for authentication	Yes*
BITBUCKET_PASSWORD	The application-specific password credential	Yes*
BITBUCKET_TOKEN	An alternative access token credential for authentication	No
BITBUCKET_WORKSPACE	A default workspace identifier if none is specified elsewhere	No

*Authentication requires either the token or both the username and password values.

Creating a Bitbucket App Password

Follow these procedural steps to generate the necessary application credentials:

1. Sign in to your designated Bitbucket account interface.
2. Navigate to the Personal Settings area, then locate App Passwords.
3. Generate a new credential set, granting it the following minimum access levels:
4. Repositories: Read access is essential.
5. Pull requests: Both Read and Write permissions must be assigned.
6. Pipelines: Read access is needed for pipeline status inquiries.
7. Securely capture the generated password; this value will supply the BITBUCKET_PASSWORD variable.

Troubleshooting

401 Authentication Errors

If the system returns a 401 status code, review these common authentication checkpoints:

1. Credential Type Check: Confirm you are utilizing an application-specific password, not your standard account login password.
2. Permission Validation: Ensure the app password possesses at least the "Repositories: Read" permission level.
3. API URL Format Test: If errors persist, explicitly configure the URL to point directly to the API endpoint: bash BITBUCKET_URL="https://api.bitbucket.org/2.0"
4. External Access Verification: Confirm credentials function correctly by querying the Bitbucket API externally: bash # Execute this command, substituting placeholders with your actual credentials curl -u "your-username:your-app-password" \ "https://api.bitbucket.org/2.0/repositories/your-workspace"5. Credential Assignment: Verify that the Atlassian API Key is placed into the BITBUCKET_PASSWORD variable, not the BITBUCKET_TOKEN field.

Getting Help

For further assistance or in the event of unexpected behavior:

1. Consult the Bitbucket REST API documentation for precise operational specifications.
2. Review the general Bitbucket Cloud documentation for platform-level support.

Integration with Cursor

Configure this MCP server within Cursor using the subsequent steps:

1. Launch the Cursor application interface.
2. Access the Settings menu and select the Extensions area.
3. Locate and select the "Model Context Protocol" setting.
4. Introduce a new configuration block named "bitbucket" following this structure:

"bitbucket": {
  "command": "npx",
  "env": {
    "BITBUCKET_URL": "https://bitbucket.org/your-workspace",
    "BITBUCKET_USERNAME": "your-username",
    "BITBUCKET_PASSWORD": "your-app-password"
  },
  "args": ["-y", "bitbucket-mcp@latest"]
}

1. Finalize the settings save operation.
2. You can now invoke Bitbucket repository and pull request features within Cursor using the /bitbucket command prefix.

Using a Local Build with Cursor

If you are actively developing this tool locally and need to test immediate modifications:

"bitbucket-local": {
  "command": "node",
  "env": {
    "BITBUCKET_URL": "https://bitbucket.org/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 implementation exposes several functionalities for managing Bitbucket resources and workflow elements. Operations are categorized below for clarity.

Repository Operations

listRepositories

Retrieves a collection of repositories hosted within a specified workspace.

Parameters:

• workspace (optional): The identifier for the target Bitbucket workspace.
• limit (optional): Sets the maximum count of repositories returned in the result set.

getRepository

Fetches detailed metadata for an individual repository based on its unique identifier.

Parameters:

• workspace: The associated Bitbucket workspace name.
• repo_slug: The repository's unique slug identifier.

Pull Request Operations

getPullRequests

Obtains a list of pull requests associated with a particular repository.

Parameters:

• workspace: The repository's owning workspace name.
• repo_slug: The repository slug.
• state (optional): Filters results by status (OPEN, MERGED, DECLINED, SUPERSEDED).
• limit (optional): Defines the maximum number of pull requests to retrieve.

createPullRequest

Initiates the creation process for a new code integration request.

Parameters:

• workspace: The repository workspace.
• repo_slug: The repository slug.
• title: The requested summary title for the changes.
• description: Detailed explanation of the purpose of the pull request.
• sourceBranch: The branch containing the proposed modifications.
• targetBranch: The branch intended to receive the changes.
• reviewers (optional): A list specifying intended code reviewers by username.
• draft (optional): Designates the request as a draft if set to true.

getPullRequest

Retrieves the complete state and details for a specific pull request instance.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique numerical identifier for the pull request.

updatePullRequest

Modifies existing attributes of a designated pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• Various optional fields like title or description can be supplied for updating.

getPullRequestActivity

Fetches the complete chronological log of events pertaining to the specified pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

approvePullRequest

Records an official approval signature against the pull request contents.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

unapprovePullRequest

Reverses a previously recorded approval action on the pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

declinePullRequest

Formally rejects the proposed changes within the pull request, halting its progression.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• message (optional): A required justification explaining the decision to decline.

mergePullRequest

Combines the source branch changes into the target branch, finalizing the integration.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• message (optional): Text to use for the resulting merge commit.
• strategy (optional): Specifies the merging technique to employ (merge-commit, squash, fast-forward).

requestChanges

Signals that modifications are still required before the pull request can be approved.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

removeChangeRequest

Cancels a previous request for changes on the pull request thread.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

createDraftPullRequest

Creates a new pull request placeholder explicitly marked as preliminary work.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• title: The title for the draft request.
• description: The description for the draft request.
• sourceBranch: The branch containing the changes.
• targetBranch: The destination branch for the changes.
• reviewers (optional): List of intended reviewers.

Note: This function behaves identically to invoking createPullRequest while setting the draft parameter to true.

publishDraftPullRequest

Transitions a pull request from draft status to an active state ready for formal review.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

convertTodraft

Reverts an active pull request back into a preliminary, non-reviewable draft status.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

Pull Request Comment Operations

getPullRequestComments

Retrieves all discussion entries attached to a specific pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

addPullRequestComment

Posts a new comment, which can be general or line-specific, onto a pull request discussion.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• content: The comment text, formatted using markdown syntax.
• inline (optional): Details specifying the exact location within a file for line-specific feedback.

Inline Comment Format:

The optional inline object specifies precise file locations for context-aware feedback:

{
  "path": "src/file.ts",
  "to": 15,     // Target line number in the newer version (for additions/modifications)
  "from": 10    // Original line number (for deletions/modifications)
} 

Examples:

• General comment: Omit the inline parameter for a standard discussion post.
• Comment on new line: Only supply the to parameter.
• Comment on deleted line: Only supply the from parameter.
• Comment on modified line: Use both from and to parameters.

Usage:

// A general discussion comment
addPullRequestComment(workspace, repo, pr_id, "Great work!")

// An inline comment on line 25 of a new file version
addPullRequestComment(workspace, repo, pr_id, "Consider error handling here", {
  path: "src/service.ts",
  to: 25
})

getPullRequestComment

Retrieves the content of a singular, identified comment within a pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• comment_id: The ID referencing the specific comment.

updatePullRequestComment

Revises the text content of an existing pull request comment.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• comment_id: The ID referencing the comment to modify.
• content: The entirely new text content for the comment.

deletePullRequestComment

Permanently removes a specified comment from the pull request thread.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• comment_id: The ID referencing the comment to remove.

resolveComment

Marks a specific comment thread as having been addressed or resolved by the participants.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• comment_id: The ID referencing the comment to resolve.

reopenComment

Reactivates a discussion thread that was previously marked as resolved.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• comment_id: The ID referencing the comment to reopen.

Pull Request Diff Operations

getPullRequestDiff

Retrieves the complete set of line-by-line changes (the diff) for the pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

getPullRequestDiffStat

Fetches summary statistics detailing additions and deletions across files in the pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

getPullRequestPatch

Obtains the pull request changes formatted as a unified patch file suitable for external application.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

Pull Request Task Operations

getPullRequestTasks

Lists all associated to-do items or action items attached to a pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

createPullRequestTask

Adds a new actionable task item directly to a pull request conversation.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• content: The specific instruction or item for the task.
• comment (optional): Links the task directly to an existing comment ID.
• pending (optional): Designates the task state as pending upon creation.

getPullRequestTask

Retrieves the current details for a single, identified task item.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• task_id: The unique identifier for the task.

updatePullRequestTask

Modifies the description or the completion status of an existing task.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• task_id: The unique identifier for the task.
• content (optional): New descriptive text for the task.
• state (optional): The new status of the task (e.g., COMPLETED).

deletePullRequestTask

Removes an associated task item from the pull request record.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.
• task_id: The unique identifier for the task.

Other Pull Request Operations

getPullRequestCommits

Lists every commit object that is incorporated within the scope of the pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

getPullRequestStatuses

Retrieves the build and verification statuses linked to the commits within the pull request.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pull_request_id: The unique identifier.

Pipeline Operations

listPipelineRuns

Shows a historical list of Continuous Integration/Continuous Delivery pipeline executions for a project.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• limit (optional): The maximum number of pipeline executions to display.
• status (optional): Filters the results by final state (PENDING, IN_PROGRESS, SUCCESSFUL, FAILED, ERROR, STOPPED).
• target_branch (optional): Filters runs targeting a specific branch name.
• trigger_type (optional): Filters by how the pipeline was initiated (manual, push, pullrequest, schedule).

getPipelineRun

Retrieves the comprehensive details regarding a single, uniquely identified pipeline execution.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pipeline_uuid: The unique identifier for the pipeline execution.

runPipeline

Initiates a new, manual execution of the defined CI/CD pipeline.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• target: An object defining the execution context (must include ref_type, ref_name, and optional fields like commit_hash).
• variables (optional): An array of key-value pairs to inject as runtime parameters into the pipeline.

stopPipeline

Sends a command to terminate a pipeline execution that is currently active.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pipeline_uuid: The unique identifier of the running pipeline.

getPipelineSteps

Lists all sequential operational steps that constitute a particular pipeline run.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pipeline_uuid: The unique identifier for the pipeline execution.

getPipelineStep

Fetches the specific status and configuration details for one step within a pipeline run.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pipeline_uuid: The unique identifier for the pipeline execution.
• step_uuid: The unique identifier for the specific step.

getPipelineStepLogs

Retrieves the standard output and error streams generated by a specific pipeline step.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The repository slug.
• pipeline_uuid: The unique identifier for the pipeline execution.
• step_uuid: The unique identifier for the specific step.

Development

Prerequisites

Ensure you have the following software components installed on your system:

• Node.js version 18 or a newer release.
• A functional package manager, either npm or yarn.

Setup

To prepare the source code for local testing or modification, follow these commands in sequence:

# Obtain the source repository files
git clone https://github.com/MatanYemini/bitbucket-mcp.git
cd bitbucket-mcp

# Install all required project dependencies
npm install

# Compile the source code into executable assets
npm run build

# Start the server in a mode suitable for immediate testing
npm run dev

Related Topics

• Distributed Version Control Systems (DVCS)
• Source Code Management (SCM)
• Code Review Processes
• Continuous Integration/Continuous Delivery (CI/CD)
• Software Feature Tracking

Extra Details

While this implementation provides extensive pull request and pipeline management, features concerning project wikis or dedicated issue tracking—common components of broader development platforms—are not directly exposed via this MCP interface. Authentication relies fundamentally on application passwords, which are distinct from standard user login credentials, offering a more granular security boundary for automated access to version control data.

Conclusion

This protocol server successfully bridges the gap between advanced AI reasoning systems and the specifics of Bitbucket's version control structure. By standardizing repository interaction, it supports organized branching, systematic code review, and automated pipeline monitoring, all vital elements in maintaining high-quality software delivery pipelines.