Atlassian Repository Context Engine

Introduction

Cloud computing represents a model for accessing shared pools of configurable resources, often virtualized, provisioned dynamically as needed. This specific service acts as a bridge, using the Model Context Protocol standard to connect large language models with data residing within Bitbucket repositories and associated development processes.

Setup

Establishing this MCP server requires a running Node.js environment, version 18 or newer. Prepare the necessary dependencies by executing standard package management commands.

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

# Install necessary package components
npm install

# Compile the project assets
npm run build

# Start the server for testing purposes
npm run dev

Installation

Running the server component is most conveniently achieved using NPX, which executes the package without a persistent local installation.

Using NPX (Recommended Method)

Execute the tool directly while supplying necessary authentication parameters via environment variables:

# Execute using NPX, setting required access details
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest

Local Installation Method

Alternatively, integration can be achieved through standard npm installation, either globally or within a specific project structure.

# Global installation procedure
npm install -g bitbucket-mcp

# Installation within a project context
npm install bitbucket-mcp

Subsequent execution, once installed locally, follows this structure:

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

# If installed as a project dependency
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp

Configuration

Connection and operational parameters are managed primarily through environment variables, ensuring sensitive credentials remain external to the core application logic.

Environment Variables

The following configuration settings control server access and behavior:

Variable	Purpose	Mandate
BITBUCKET_URL	The primary connection endpoint for Bitbucket services.	Essential
BITBUCKET_USERNAME	The identifying user for authentication.	Essential*
BITBUCKET_PASSWORD	The application-specific password for access.	Essential*
BITBUCKET_TOKEN	An alternative, single access token approach.	Optional
BITBUCKET_WORKSPACE	The default workspace to query if not explicitly provided.	Optional

*Authentication requires either the BITBUCKET_TOKEN or the combination of BITBUCKET_USERNAME and BITBUCKET_PASSWORD must be supplied.

Generating an Application Password

To establish secure connectivity, follow these steps to generate a necessary App Password within Bitbucket:

1. Log in to your Bitbucket interface.
2. Navigate to Personal Settings, then locate App Passwords.
3. Generate a new password, specifying required permissions.
4. Repositories: Read access is fundamental.
5. Pull requests: Read and Write capabilities are needed for workflow actions.
6. Pipelines: Read access supports pipeline monitoring.
7. Record the generated password, employing it as the value for the BITBUCKET_PASSWORD variable.

Integration with Cursor

Connecting this server to the Cursor AI assistant involves configuring a new Model Context Protocol endpoint within its settings interface.

1. Open the Cursor application and access its configuration options.
2. Navigate to the Extensions section.
3. Select the entry labeled "Model Context Protocol".
4. Add a new configuration block using the following 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. Save the updated settings file.
2. You can then invoke the Bitbucket context provider within Cursor using the /bitbucket directive.

Using a Local Build with Cursor

Developers testing modifications locally should point the configuration to the compiled local output path:

"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"]
}

Troubleshooting

Authentication issues frequently manifest as HTTP 401 responses during external service calls.

Resolving 401 Authentication Errors

Systematically check these common failure points if access is denied:

1. Password Verification: Confirm you are utilizing an App Password, distinctly separate from your standard login credential.
2. Permission Validation: Ensure the App Password holds adequate minimum permissions, specifically "Repositories: Read".
3. API URL Format Check: If errors persist, try explicitly setting the URL to the direct API endpoint: bash BITBUCKET_URL="https://api.bitbucket.org/2.0"
4. Manual Credential Test: Validate connectivity externally using a command-line utility like curl: bash # Execute test using credentials (substitute placeholders) curl -u "your-username:your-app-password" \ "https://api.bitbucket.org/2.0/repositories/your-workspace"
5. Variable Assignment Clarification: Confirm the Atlassian API Key is assigned to BITBUCKET_PASSWORD, not BITBUCKET_TOKEN.

Available Tools

This server exposes a standardized set of methods for resource access and manipulation within the connected Bitbucket environment.

Repository Operations

listRepositories

Retrieves a list of repositories belonging to a specified workspace.

Parameters:

• workspace (optional): Identifier for the target workspace.
• limit (optional): Controls the maximum quantity of results returned.

getRepository

Fetches detailed metadata for one particular repository.

Parameters:

• workspace: The workspace identifier.
• repo_slug: The unique slug identifying the repository.

Pull Request Operations

getPullRequests

Lists all pull requests associated with a repository, filterable by status.

Parameters:

• workspace: The managing workspace.
• repo_slug: The repository slug.
• state (optional): Filter by status, such as OPEN, MERGED, or DECLINED.
• limit (optional): Maximum number of requests to retrieve.

createPullRequest

Initiates the creation process for a new pull request resource.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• title: The subject line for the request.
• description: Detailed explanation formatted in text.
• sourceBranch: The branch containing the changes.
• targetBranch: The destination branch for integration.
• reviewers (optional): A list of usernames designated as reviewers.
• draft (optional): Designates the request as a draft if set to true.

getPullRequest

Retrieves comprehensive information pertaining to a single pull request instance.

Parameters:

• workspace: Workspace identifier.
• repo_slug: Repository slug.
• pull_request_id: Unique identifier for the pull request.

updatePullRequest

Modifies existing attributes of a specified pull request.

Parameters:

• workspace: Workspace context.
• repo_slug: Repository context.
• pull_request_id: The PR identifier.
• Various optional parameters allow modification of fields like the title or description.

getPullRequestActivity

Fetches the chronological log of all events associated with a specific pull request.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request being inspected.

approvePullRequest

Records an official approval action against the specified pull request.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

unapprovePullRequest

Reverts a previously submitted approval for the pull request.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

declinePullRequest

Marks the pull request as declined, typically closing it without merging.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.
• message (optional): A required explanation detailing the rejection reason.

mergePullRequest

Combines the source branch changes into the target branch, creating a commit if necessary.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.
• message (optional): Text to use for the resulting merge commit.
• strategy (optional): Specifies the merging technique, such as squash or fast-forward.

requestChanges

Explicitly notifies the author that modifications are still required before approval.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

removeChangeRequest

Removes an existing change request note from a pull request record.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

createDraftPullRequest

Creates a new pull request initialized in a draft state, preventing automatic review triggers.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• title: Title for the draft.
• description: Supporting documentation.
• sourceBranch: Branch containing changes.
• targetBranch: Branch target.
• reviewers (optional): List of initial reviewers.

Note: This function achieves the same result as invoking createPullRequest while setting the draft parameter to true.

publishDraftPullRequest

Transitions a draft pull request into an active, review-ready state.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the draft PR.

convertTodraft

Reverts an active pull request back into a draft status for further, non-public edits.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the active PR.

Pull Request Comment Operations

getPullRequestComments

Fetches all discussion entries recorded against a pull request.

Parameters:

• workspace: Workspace context.
• repo_slug: Repository context.
• pull_request_id: The PR identifier.

addPullRequestComment

Posts a new comment, which can be general or contextually linked to specific lines of code.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.
• content: The text body of the comment, supporting Markdown.
• inline (optional): Structure detailing file path and line numbers for line-specific comments.

Inline Comment Format: The inline structure specifies location context using file paths and line indicators:

{
  "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) 
}

Usage:

// General context comment
addPullRequestComment(workspace, repo, pr_id, "Excellent implementation.")

// Inline comment targeting line 25 of a newly added section
addPullRequestComment(workspace, repo, pr_id, "Review this logic path.", {
  path: "src/service.ts",
  to: 25
})

getPullRequestComment

Retrieves the content of an individually identified comment.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• comment_id: Unique identifier for the specific comment.

updatePullRequestComment

Revises the text content of an existing comment.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• comment_id: Target comment ID.
• content: The revised textual content.

deletePullRequestComment

Permanently removes a comment from the discussion thread.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• comment_id: Target comment ID.

resolveComment

Marks a specific comment thread as resolved, indicating the issue has been addressed.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• comment_id: Target comment ID.

reopenComment

Re-activates a previously resolved comment thread, signaling that discussion needs resumption.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• comment_id: Target comment ID.

Pull Request Diff Operations

getPullRequestDiff

Obtains the complete file differences represented by the pull request changeset.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

getPullRequestDiffStat

Retrieves statistics summarizing the magnitude of changes (lines added/removed) within the PR.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

getPullRequestPatch

Downloads the content representing the pull request changes in standard patch format.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

Pull Request Task Operations

getPullRequestTasks

Lists all actionable tasks or to-dos tracked within a pull request.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

createPullRequestTask

Adds a new, trackable task item to the pull request context.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.
• content: The descriptive text of the task.
• comment (optional): Associates the task with an existing comment ID.
• pending (optional): Sets the initial state of the task to pending.

getPullRequestTask

Retrieves the specific details for one task associated with a pull request.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• task_id: Unique identifier for the task.

updatePullRequestTask

Modifies the content or completion status of an existing task.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• task_id: Target task ID.
• content (optional): New task description.
• state (optional): Update to a new state, like completed or pending.

deletePullRequestTask

Removes a task entry from the pull request record entirely.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Pull request identifier.
• task_id: Target task ID.

Other Pull Request Operations

getPullRequestCommits

Lists all individual commits included within the scope of the pull request.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

getPullRequestStatuses

Retrieves aggregated status checks (like CI results) linked to the pull request commits.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pull_request_id: Identifier for the pull request.

Pipeline Operations

listPipelineRuns

Generates a list of all historical pipeline executions for a given repository.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• limit (optional): Limits the returned number of pipeline runs.
• status (optional): Filters results by execution outcome, e.g., SUCCESSFUL or FAILED.
• target_branch (optional): Filters by the branch the pipeline acted upon.
• trigger_type (optional): Filters based on how the pipeline was invoked.

getPipelineRun

Retrieves the full execution report for a specific pipeline instance, identified by its UUID.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pipeline_uuid: The unique identifier for the run.

runPipeline

Manually initiates a new execution of an existing pipeline configuration.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• target: Configuration object defining the run context (branch, commit, etc.).
• variables (optional): Custom key-value pairs passed to the pipeline environment.

stopPipeline

Attempts to terminate a pipeline that is currently active or waiting.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pipeline_uuid: Identifier for the running pipeline.

getPipelineSteps

Lists the distinct stages or steps executed within a complete pipeline run.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pipeline_uuid: Identifier for the pipeline run.

getPipelineStep

Fetches detailed execution data for an individual step within a pipeline.

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pipeline_uuid: Pipeline run identifier.
• step_uuid: Unique identifier for the specific step.

getPipelineStepLogs

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

Parameters:

• workspace: Workspace name.
• repo_slug: Repository slug.
• pipeline_uuid: Pipeline run identifier.
• step_uuid: Specific step identifier.

Development

This section outlines the requirements and procedure for local modification and testing of the tool.

Prerequisites

Ensure the following runtime components are present on the development machine before proceeding.

• Node.js (version 18 or higher is required).
• A compatible package manager, such as npm or yarn.

Setup

To prepare the local environment for code contribution, follow these steps:

# Obtain the source code via Git cloning
git clone https://github.com/MatanYemini/bitbucket-mcp.git
cd bitbucket-mcp

# Install all necessary dependencies
npm install

# Compile source files into executable artifacts
npm run build

# Run the server in an active development loop
npm run dev

Related Topics

• Cloud Computing: A technology paradigm defined by self-service resource access over a network, adhering to scalable and elastic provisioning principles (ISO definition).
• Software Repository: Centralized systems for version control, managing source code history and collaboration artifacts like Bitbucket.
• Pull Request (PR) Workflow: The standard code review mechanism used to integrate feature branches into main development lines.
• CodeQL: A semantic code analysis engine used here to enforce security standards within proposed code changes.
• Model Context Protocol (MCP): A defined standard facilitating communication between language models and external data sources.

Extra Details

Although this server enables extensive management of pull requests, including creation, approval, and merging, it is deliberately engineered to exclude any commands capable of executing DELETE operations. This architectural constraint prevents accidental or malicious data destruction, which is a crucial security consideration in any cloud-service context handling critical source code.

Conclusion

This MCP implementation successfully virtualizes the Bitbucket interface, making repository contents and change management accessible via a standardized protocol. By prioritizing read access, security scanning, and non-destructive operations, it offers reliable, context-aware data for advanced automated reasoning within cloud-based AI workflows.