Bitbucket MCP Server

A Model Context Protocol (MCP) server for Bitbucket Cloud and Server APIs, built with TypeScript and Node.js. Provides comprehensive tools for repository management, pull requests, branches, commits, and file operations.

Features

• Dual API Support - Bitbucket Cloud API v2 and Server API v1.0 (auto-detected by base URL)
• 25+ MCP Tools - Complete coverage of Bitbucket operations
• Flexible Configuration - Environment variables or JSON config files
• Smart Defaults - Auto-detects current branch for PR creation
• Structured Errors - Detailed error responses with suggestions
• TypeScript - Full type safety and modern ES modules

Installation

Using npm (Global)

npm install -g @yogeshrathod/bitbucket-mcp

Using npx (No Installation)

npx @yogeshrathod/bitbucket-mcp

Updating

Update Global Installation

npm update -g @yogeshrathod/bitbucket-mcp

Update to Latest with npx

npx @yogeshrathod/bitbucket-mcp@latest

Check Current Version

npm list -g @yogeshrathod/bitbucket-mcp

Configuration

Configure the server using environment variables or a JSON config file.

Environment Variables

export ATLASSIAN_SITE_URL="bitbucket"  # or your server URL
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your-app-password-or-pat"

| Variable | Description | | ---------------------- | ----------------------------------------------------------------------------------------- | | ATLASSIAN_SITE_URL | bitbucket for Cloud API, or full URL for Server (e.g., https://bitbucket.company.com) | | ATLASSIAN_USER_EMAIL | Your Bitbucket account email | | ATLASSIAN_API_TOKEN | App Password (Cloud) or Personal Access Token (Server) |

JSON Config File

Create one of these files in your working directory: mcp.config.json, .mcp.config.json, or .bitbucket.mcp.json

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_SITE_URL": "bitbucket",
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your-app-password"
    }
  }
}

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop, Windsurf):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@yogeshrathod/bitbucket-mcp"],
      "env": {
        "ATLASSIAN_SITE_URL": "bitbucket",
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-app-password"
      }
    }
  }
}

Tools Reference

All repository-specific tools require workspace and repoSlug parameters.

Connection & Discovery

| Tool | Description | Parameters | | ----------------- | -------------------------------- | ----------------------- | | connection_test | Test connection to Bitbucket API | - | | workspaces_list | List all accessible workspaces | - | | repos_list | List repositories in a workspace | workspace | | repo_info | Get repository details | workspace, repoSlug |

Pull Requests

| Tool | Description | Parameters | | ------------------ | --------------------------- | ----------------------------------------------------------------------------------- | | pr_list | List pull requests | workspace, repoSlug, state? (OPEN|MERGED|DECLINED|SUPERSEDED) | | pr_create | Create a pull request | workspace, repoSlug, title, sourceBranch?, destBranch?, description? | | pr_get | Get PR details | workspace, repoSlug, prId | | pr_update | Update PR title/description | workspace, repoSlug, prId, title?, description? | | pr_diff | Get PR diff | workspace, repoSlug, prId | | pr_changes | Get file changes in PR | workspace, repoSlug, prId | | pr_approve | Approve a PR | workspace, repoSlug, prId | | pr_decline | Decline/reject a PR | workspace, repoSlug, prId | | pr_merge | Merge a PR | workspace, repoSlug, prId, closeSourceBranch?, mergeStrategy?, message? | | pr_comment_add | Add comment to PR | workspace, repoSlug, prId, text | | pr_comments_list | List PR comments | workspace, repoSlug, prId | | pr_reviewers_add | Add reviewers to PR | workspace, repoSlug, prId, reviewers (array) |

Branches

| Tool | Description | Parameters | | ---------------- | -------------------- | ------------------------------------------------ | | branches_list | List branches | workspace, repoSlug | | branch_create | Create a branch | workspace, repoSlug, name, targetHash | | branch_compare | Compare two branches | workspace, repoSlug, source, destination |

Commits

| Tool | Description | Parameters | | -------------- | ------------------ | ------------------------------------- | | commits_list | List commits | workspace, repoSlug, spec? | | commit_get | Get commit details | workspace, repoSlug, commitHash | | commit_diff | Get commit diff | workspace, repoSlug, commitHash |

Files

| Tool | Description | Parameters | | -------------- | -------------------------- | ------------------------------------------------- | | file_content | Get file content at commit | workspace, repoSlug, filePath, commitHash |

Usage Examples

List Open Pull Requests

{
  "tool": "pr_list",
  "arguments": {
    "workspace": "my-workspace",
    "repoSlug": "my-repo",
    "state": "OPEN"
  }
}

Create a Pull Request

{
  "tool": "pr_create",
  "arguments": {
    "workspace": "my-workspace",
    "repoSlug": "my-repo",
    "title": "Add new feature",
    "sourceBranch": "feature/my-feature",
    "destBranch": "main",
    "description": "This PR adds a new feature"
  }
}

Merge a Pull Request

{
  "tool": "pr_merge",
  "arguments": {
    "workspace": "my-workspace",
    "repoSlug": "my-repo",
    "prId": 123,
    "mergeStrategy": "squash",
    "closeSourceBranch": true
  }
}

Compare Branches

{
  "tool": "branch_compare",
  "arguments": {
    "workspace": "my-workspace",
    "repoSlug": "my-repo",
    "source": "feature/my-feature",
    "destination": "main"
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Start development server
npm start

Requirements

• Node.js >= 18.17.0
• Bitbucket Cloud App Password or Server Personal Access Token

License

MIT © Yogesh Rathod