Bitbucket MCP

5.0.6 verified Sat Apr 25 auth: no javascript

A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs. Version 5.0.6, actively maintained. Allows AI assistants (e.g., Cursor) to interact with Bitbucket repositories and pull requests via tool calls. Safe design: no DELETE operations. Requires Node >=18. ESM-only. Supports both Bitbucket Cloud and Server via configuration.

Common errors

error Error: Cannot find module 'bitbucket-mcp' ↓

cause Bitbucket MCP is not installed or not in node_modules.

fix

Run 'npm install bitbucket-mcp' in your project directory.

error Error: Workspace is required ↓

cause BITBUCKET_WORKSPACE environment variable is not set.

fix

Set the BITBUCKET_WORKSPACE env var to your Bitbucket workspace.

error Error: Authentication failed (401) ↓

cause Invalid or missing username/app password credentials.

fix

Ensure BITBUCKET_USERNAME and BITBUCKET_PASSWORD are set correctly.

Warnings

breaking In v5.0.0, the environment variable BITBUCKET_REPOSITORY was removed; use BITBUCKET_WORKSPACE instead. ↓

fix Set BITBUCKET_WORKSPACE env var instead of BITBUCKET_REPOSITORY.

breaking In v5.0.0, the legacy env var BITBUCKET_API_URL was replaced by BITBUCKET_URL. ↓

fix Use BITBUCKET_URL instead of BITBUCKET_API_URL.

deprecated Option B (web URL only) for BITBUCKET_URL is deprecated since v5.0.0; workspace auto-extraction will be removed in the future. ↓

fix Use Option A: set BITBUCKET_URL to 'https://api.bitbucket.org/2.0' and explicitly set BITBUCKET_WORKSPACE.

gotcha The package is ESM-only: cannot be imported with require(). ↓

fix Use import syntax or dynamic import().

Install

npm install bitbucket-mcp

yarn add bitbucket-mcp

pnpm add bitbucket-mcp

Imports

BitbucketServer

wrong

const BitbucketServer = require('bitbucket-mcp')

correct

import { BitbucketServer } from 'bitbucket-mcp'

ESM-only package; named export.

BitbucketCloud

wrong

import BitbucketCloud from 'bitbucket-mcp'

correct

import { BitbucketCloud } from 'bitbucket-mcp'

Named export, not default.

createServer

wrong

import { startServer } from 'bitbucket-mcp'

correct

import { createServer } from 'bitbucket-mcp'

Correct function is named 'createServer'.

Quickstart

Creates and starts an MCP server connected to Bitbucket Cloud, using environment variables for authentication and workspace.

import { createServer } from 'bitbucket-mcp';

const server = createServer({
  url: process.env.BITBUCKET_URL || 'https://api.bitbucket.org/2.0',
  username: process.env.BITBUCKET_USERNAME ?? '',
  password: process.env.BITBUCKET_PASSWORD ?? '',
  workspace: process.env.BITBUCKET_WORKSPACE ?? ''
});

server.listen(3100).then(() => {
  console.log('Bitbucket MCP server running on port 3100');
});