Bitbucket Server Model Context Protocol Server

1.10.8 · active · verified Tue Apr 21

mcp-bitbucket-server is a Model Context Protocol (MCP) server designed to connect AI assistants, such as Claude, to Bitbucket Server/Data Center instances. It enables natural language interaction for tasks like reviewing pull requests, managing repositories, searching users, and adding comments directly from an AI interface. The current stable version is 1.10.8. While no explicit release cadence is stated, the use of `npx mcp-bitbucket-server@latest` suggests frequent updates and maintenance. Key differentiators include its focus on the MCP standard, providing 11 specialized tools for Bitbucket operations, optimizing responses to reduce AI token usage, and utilizing Bitbucket Personal Access Tokens for secure authentication rather than OAuth or more complex schemes. It supports Node.js versions 22.0.0 and newer.

Common errors

```
"Authentication failed"
```
cause The provided Personal Access Token is incorrect, expired, or revoked.

fix Generate a new Personal Access Token in Bitbucket Server and ensure it is correctly configured as `BITBUCKET_TOKEN`.
```
"Access forbidden"
```
cause The Personal Access Token has insufficient permissions for the requested operation or the associated user lacks necessary Bitbucket roles.

fix Check the project and repository permissions associated with your Personal Access Token and ensure they match the required scope (e.g., 'Read' or 'Write').

Warnings

gotcha Ensure your Node.js environment meets the minimum version requirement (>=22.0.0). Running with older versions may lead to runtime errors or unexpected behavior.
Fix: Upgrade your Node.js installation to version 22.0.0 or higher.
gotcha Personal Access Tokens (PATs) must be created with sufficient permissions for the intended operations. For example, commenting on PRs requires 'Write' project/repository permissions, while listing PRs only requires 'Read'.
Fix: Verify and adjust the permissions of your Bitbucket Personal Access Token in your Bitbucket Server profile settings.
gotcha Always use environment variables or a secure configuration mechanism to store your Bitbucket Personal Access Token, as exposing it directly in scripts or version control is a security risk.
Fix: Utilize environment variables (e.g., `BITBUCKET_TOKEN`) or a secrets management system provided by your MCP client or operating environment.

Install

npm install mcp-bitbucket-server npm
yarn add mcp-bitbucket-server yarn
pnpm add mcp-bitbucket-server pnpm

Imports

runMcpServer
wrong:
```
const runMcpServer = require('mcp-bitbucket-server').runMcpServer;
```
correct:
```
import { runMcpServer } from 'mcp-bitbucket-server';
```
While primarily run via npx, this symbol could be used for programmatic embedding or testing the server within a TypeScript/JavaScript application.
BitbucketTool
```
import type { BitbucketTool } from 'mcp-bitbucket-server';
```
This type represents the interface for a Bitbucket-specific MCP tool. Useful for developers extending or understanding the server's capabilities.
configureServer
```
import { configureServer } from 'mcp-bitbucket-server';
```
Hypothetical export for configuring the server programmatically, useful for advanced setups or testing environments where direct command execution is not preferred.

Quickstart

This command registers the Bitbucket Server MCP with the Claude Code CLI, setting up environment variables for the Bitbucket URL and a Personal Access Token.

claude mcp add -s user \
    bitbucket-server \
    npx mcp-bitbucket-server@latest \
    -e "BITBUCKET_URL=https://bitbucket.yourcompany.com" \
    -e "BITBUCKET_TOKEN=your_personal_access_token"

view raw JSON →