Bitbucket MCP Server

Bitbucket MCP is a Model Context Protocol (MCP) server that integrates Bitbucket Cloud and Server APIs with AI assistants like Cursor. It provides tools for interacting with Bitbucket resources, including:

• Listing and retrieving repositories
• Getting repository details
• Fetching pull requests
• Other Bitbucket data and operations

By default, the server is safe and does not perform DELETE operations unless explicitly enabled.

Most tools that return lists of items (repositories, pull requests, pipelines, etc.) support pagination to prevent CLI truncation and manage large datasets. You can use the following parameters:

• pagelen: Number of items per page (Bitbucket pagelen). Defaults to 10; maximum is 100. Note that limit is a deprecated alias for pagelen.
• page: The 1-based page number to fetch. If omitted, the first page is returned.
• all: When set to 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.

To use BITBUCKET_PASSWORD, you must create an App Password in Bitbucket with the following permissions:

1. Log in to Bitbucket.
2. Go to Personal Settings > App Passwords.
3. Create a new password with these permissions:
   • Repositories: Read
   • Pull requests: Read, Write
   • Pipelines: Read (required for pipeline operations)
4. Copy the generated password.

When releasing a new version of the server to the Model Context Protocol (MCP) registry, follow these steps to prepare the manifest:

1. Build the project: Ensure dist/index.js is up to date.
2. Generate the manifest: Run the registry manifest command to create registry/bitbucket-mcp.manifest.json. This manifest automatically captures the CLI command (node dist/index.js), configuration options, and setup documentation.
3. Publish: Follow the official publish-server guide using smithery publish or the recommended workflow.

# 1. Build the project
npm run build

# 2. Generate the registry manifest
npm run registry:manifest

To develop on the bitbucket-mcp project, ensure you have Node.js 18 or higher and a package manager (npm or yarn) installed. Follow these steps to clone, build, and run the project locally:

1. Clone the repository.
2. Install dependencies.
3. Build the project to generate the dist/ directory.
4. Run the development command.

# 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

You can install the package globally or locally within a project using npm.

Global Installation: npm install -g bitbucket-mcp

Project Installation: npm install bitbucket-mcp

# Install globally
npm install -g bitbucket-mcp

# Or install in your project
npm install bitbucket-mcp

The recommended way to run the server without a global installation is using npx. You can choose between two configuration patterns:

Option A (Recommended): Provide the API URL and an explicit workspace. Option B (Legacy-compatible): Provide a web URL only; the workspace is automatically extracted from the URL.

Note: BITBUCKET_USERNAME is typically your Bitbucket email address.

# 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

If you encounter 401 errors, follow these steps:

1. Verify App Password: Ensure you are using an App Password, not your regular Bitbucket account password.
2. Check Permissions: Ensure the App Password has at least Repositories: Read permission.
3. Verify API URL: Try using the direct API URL format: BITBUCKET_URL="https://api.bitbucket.org/2.0".
4. Test with curl: Verify credentials manually: curl -u "your-username:your-app-password" "https://api.bitbucket.org/2.0/repositories/your-workspace".
5. Atlassian API Keys: If using an Atlassian API Key, put it in BITBUCKET_PASSWORD (not BITBUCKET_TOKEN) and use your Bitbucket email as BITBUCKET_USERNAME.

# Test with curl (replace with your actual values)
curl -u "your-username:your-app-password" \
  "https://api.bitbucket.org/2.0/repositories/your-workspace"

Tools for interacting with Bitbucket Pipelines:

• listPipelineRuns: Lists runs for a repository. Supports status (PENDING, IN_PROGRESS, SUCCESSFUL, FAILED, ERROR, STOPPED), target_branch, trigger_type (manual, push, pullrequest, schedule), and pagination.
• getPipelineRun: Gets details for a specific run using pipeline_uuid.
• runPipeline: Triggers a new run. Requires workspace, repo_slug, and target (object with ref_type, ref_name, and optional commit_hash, selector_type, selector_pattern). Optional: variables (array of {key, value, secured}).
• stopPipeline: Stops a running pipeline using pipeline_uuid.
• getPipelineSteps: Lists steps for a run.
• getPipelineStep: Gets details for a specific step using step_uuid.
• getPipelineStepLogs: Gets logs for a specific step.