bitbucket-cloud-mcp-server

Bitbucket Cloud MCP

MCP (Model Context Protocol) server for Bitbucket Cloud Pull Request management. This server provides read-only tools to interact with the Bitbucket Cloud API through the Model Context Protocol.

Requirements

• Node.js >= 18

Installation

Manual Installation

npm install

Build

npm run build

Features

The server provides the following read-only MCP tools for Bitbucket Cloud integration:

get_bb_pull_request

Retrieves detailed information about a specific pull request.

Parameters:

• workspace (required): Bitbucket workspace
• repo_slug (required): Repository slug
• pull_request_id (required): Pull request ID

get_bb_diff

Gets the diff for a pull request.

Parameters:

• workspace (required): Bitbucket workspace
• repo_slug (required): Repository slug
• pull_request_id (required): Pull request ID

Dependencies

• @modelcontextprotocol/sdk - Model Context Protocol SDK
• axios - HTTP client for API requests
• winston - Logging framework
• dotenv - Environment variable management

Configuration

The server requires configuration in the MCP client settings. Here's a sample configuration for VSCode:

{
  "mcpServers": {
    "bitbucket-cloud": {
      "command": "node",
      "args": ["/path/to/bitbucket-cloud-mcp-server/build/index.js"],
      "env": {
        // Required: Bitbucket Cloud Personal Access Token
        "BITBUCKET_TOKEN": "your-bitbucket-cloud-token-here",
        // Optional: Default Bitbucket workspace/owner
        "BITBUCKET_WORKSPACE": "your-bitbucket-workspace-here"
      }
    }
  }
}

Environment Variables

• BITBUCKET_TOKEN (required): Personal access token from Bitbucket Cloud
  • Required permissions: Repository read, Pull request read
  • Can be generated from: Bitbucket Cloud > Personal Settings > App passwords
• BITBUCKET_WORKSPACE (optional): Default Bitbucket workspace/owner to use

Development

Running Tests

npm test

Local Development

1. Copy .env.example to .env
2. Set your Bitbucket Cloud token in .env
3. Run npm start for development

Parameter Compatibility Notes

For backward compatibility, this server accepts the following parameter mappings:

• workspace for Bitbucket workspace
• repo_slug for repository slug
• pull_request_id for Pull Request ID

Model Context Protocol

This server implements the Model Context Protocol (MCP), a standard protocol for AI tools that allows AI assistants to:

1. Discover available tools
2. Understand tool capabilities and required parameters
3. Call tools with appropriate parameters
4. Receive structured responses

The MCP implementation uses the @modelcontextprotocol/sdk package to facilitate communication between the AI assistant and the Bitbucket Cloud API.