bitbucket-mcp

Bitbucket MCP

Model Context Protocol (MCP) server for Bitbucket Cloud and Server API integration. This package enables AI assistants to interact with Bitbucket repositories, pull requests, and other features through the MCP protocol.

Features

• Bitbucket Cloud API Integration: Access the full Bitbucket Cloud REST API
• Bitbucket Server Support: Compatible with Bitbucket Server instances
• Repository Management: List, view, and manage repositories
• Pull Request Operations: Create, view, merge, and comment on PRs
• Permission Management: Query and manage repository permissions
• Webhook Management: List and manage webhooks

Installation

# Install globally
npm install -g bitbucket-mcp

# Or run directly with npx
npx bitbucket-mcp

Quick Start

• Set up your environment variables:

# Required for all operations
export BITBUCKET_URL="https://your-bitbucket-server-url"  # For Server API
export BITBUCKET_CLOUD_URL="https://api.bitbucket.org/2.0"  # For Cloud API

# Authentication (choose one method)
export BITBUCKET_TOKEN="your_access_token"
# OR
export BITBUCKET_USERNAME="your_username"
export BITBUCKET_APP_PASSWORD="your_app_password"

# Optional
export BITBUCKET_DEFAULT_PROJECT="your_default_project"  # For Server API

• Run the MCP server:

npx bitbucket-mcp

Supported API Operations

Bitbucket Cloud Repository API

• list_public_repositories - List all public repositories
• list_workspace_repositories - List repositories in a workspace
• get_repository - Get a specific repository
• list_repository_forks - List forks of a repository
• list_repository_webhooks - List webhooks for a repository
• get_repository_webhook - Get a specific webhook
• get_repository_settings_inheritance - Get repository settings inheritance
• list_repository_group_permissions - List group permissions
• get_repository_group_permission - Get specific group permission
• list_repository_user_permissions - List user permissions
• get_repository_user_permission - Get specific user permission
• list_repository_watchers - List repository watchers
• list_user_repository_permissions - List permissions for the current user

Bitbucket Server Pull Request API

• create_pull_request - Create a new pull request
• get_pull_request - Get pull request details
• merge_pull_request - Merge a pull request
• decline_pull_request - Decline a pull request
• add_comment - Add a comment to a pull request
• get_diff - Get pull request diff
• get_reviews - Get pull request reviews

Integration with AI Assistants

This MCP server is designed to be used with AI assistants that support the Model Context Protocol:

Using with Claude

• Install the Claude desktop app
• Add this MCP server to Claude:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_CLOUD_URL": "https://api.bitbucket.org/2.0",
        "BITBUCKET_TOKEN": "your-access-token"
      }
    }
  }
}

Using with other MCP clients

Any client that supports the MCP protocol can communicate with this server over standard input/output.

API Examples

List repositories in a workspace

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "mcp.call_tool",
  "params": {
    "name": "list_workspace_repositories",
    "arguments": {
      "workspace": "your_workspace"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"values\": [...], \"pagelen\": 10, ... }"
      }
    ]
  }
}

Create a pull request

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "mcp.call_tool",
  "params": {
    "name": "create_pull_request",
    "arguments": {
      "project": "PROJECT",
      "repository": "repo-name",
      "title": "Feature: Add new functionality",
      "description": "This PR adds the new feature X",
      "sourceBranch": "feature/new-feature",
      "targetBranch": "main"
    }
  }
}

Development

# Clone the repository
git clone https://github.com/yourusername/bitbucket-mcp.git
cd bitbucket-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

Logging

The server logs all operations to bitbucket.log using Winston for debugging and monitoring purposes.

License

MIT