by MatanYemini
Bitbucket MCP - A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs
# Add to your Claude Code skills
git clone https://github.com/MatanYemini/bitbucket-mcpA 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:
-- 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:
# 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
No comments yet. Be the first to share your thoughts!
Alternatively, you can install it globally or as part of your project:
# Install globally
npm install -g bitbucket-mcp
# Or install in your project
npm install bitbucket-mcp
Then run it with:
# 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-mcp
# If installed globally (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp
# If 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-mcp
# If 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
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.
BITBUCKET_PASSWORD environment variableIf you're getting 401 authentication errors, check the following:
BITBUCKET_URL="https://api.bitbucket.org/2.0"
# Test with curl (replace with your actual values)
curl -u "your-username:your-app-password" \
"https://api.bitbucket.org/2.0/repositories/your-workspace"
BITBUCKET_PASSWORD variable, not BITBUCKET_TOKENBITBUCKET_USERNAME instead of your regular usernameFor reference you can check the API token documentation
If you encounter issues:
To integrate this MCP server with Cursor:
"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"]
}
If you're developing locally and want to test your changes:
"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"]
}
This MCP server provides tools for interacting with Bitbucket repositories and pull requests. Below is a comprehensive list of the available operations:
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.
listRepositoriesLists repositories in a workspace.
Parameters:
workspace (optional): Bitbucket workspace namename (optional): Filter repositories by partial name matchgetRepositoryGets details for a specific repository.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository sluggetPullRequestsGets pull requests for a repository.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugstate (optional): Pull request state (OPEN, MERGED, DECLINED, SUPERSEDED)createPullRequestCreates a new pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugtitle: Pull request titledescription: Pull request descriptionsourceBranch: Source branch nametargetBranch: Target branch namereviewers (optional): List of reviewer usernamesdraft (optional): Whether to create the pull request as a draftgetPullRequestGets details for a specific pull request.
Parameters:
workspace: Bitbucket workspace namerepo_slug: Repository slugpull_request_id: Pull request ID