Bitbucket MCP Server

A TypeScript MCP server that enables AI agents to interact with Bitbucket Cloud repositories, pull requests, and branches.

Quick Start (npx)

No installation needed — run directly via npx:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@rexymayderio/bitbucket-mcp"],
      "env": {
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_REPOSITORY": "your-repository"
      }
    }
  }
}

Add this to your MCP client config (e.g. ~/.kiro/settings/mcp.json, ~/.cursor/mcp.json, or similar).

Environment Variables

| Variable | Required | Description | | ---------------------- | -------- | -------------------------------------------------------------------------- | | ATLASSIAN_EMAIL | Yes | Your Atlassian account email | | ATLASSIAN_API_TOKEN | Yes | API token from https://id.atlassian.com/manage-profile/security/api-tokens | | BITBUCKET_WORKSPACE | No | Default workspace (can be provided per tool call instead) | | BITBUCKET_REPOSITORY | No | Default repository (can be provided per tool call instead) |

Features

Smart Parameter Handling

• URL Extraction: Automatically extracts workspace and repository from Bitbucket URLs
• Environment Fallbacks: Uses BITBUCKET_WORKSPACE and BITBUCKET_REPOSITORY as defaults
• Helpful Error Messages: Clear instructions when parameters are missing

Priority Order: Direct parameters > URL extraction > Environment variables

Repository Operations

| Tool | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | read_repository | Get repository info (name, description, default branch, permissions), list branches, tags, and recent commits | | read_branch | Get branch details (name, latest commit, author, date), compare branch with main/master | | read_commit | Get commit details (message, author, date, diff), parse Jira ticket references | | read_file | Read file content from any branch/tag/commit | | search_code | Search across repositories by content, file path, or extension |

Pull Request Operations

| Tool | Description | | --------------------- | ------------------------------------------------------------------------------------------ | | list_pull_requests | List PRs by status (open, merged, declined), filter by author or Jira ticket | | read_pull_request | Get PR details (title, description, status, reviewers, diff, comments, approvals) | | create_pull_request | Create PR with auto-generated description from commits, auto-link Jira tickets | | update_pull_request | Update PR title/description/status, add reviewers, add comments (general or inline), merge | | reply_to_comment | Reply to an existing PR comment (threaded replies) |

Branch Operations

| Tool | Description | | --------------- | ----------------------------------------------------------- | | delete_branch | Delete branch with safety checks, optionally only if merged |

File Operations

| Tool | Description | | -------------- | ------------------------------------------------------------------------ | | write_file | Write or update a single file (creates a commit on the specified branch) | | commit_files | Commit multiple files in a single atomic commit |

Usage Examples

Using URLs for Workspace/Repository

All tools support extracting workspace and repository from Bitbucket URLs:

{
  "prUrl": "https://bitbucket.org/myworkspace/myrepo/pull-requests/123",
  "includeDiff": true
}

read_pull_request

{
  "prUrl": "https://bitbucket.org/myworkspace/myrepo/pull-requests/123",
  "includeDiff": true,
  "includeComments": true
}

create_pull_request

{
  "title": "Add new feature",
  "sourceBranch": "feature/new-feature",
  "destinationBranch": "main",
  "reviewers": ["reviewer1"],
  "autoGenerateDescription": true
}

update_pull_request (inline comment)

{
  "prUrl": "https://bitbucket.org/myworkspace/myrepo/pull-requests/123",
  "comment": "Consider adding error handling here",
  "commentFilePath": "src/models/BiFastDetail.ts",
  "commentLineNumber": 42
}

commit_files

{
  "branch": "feature/multi-file-update",
  "message": "Update multiple configuration files",
  "files": [
    { "path": "package.json", "content": "{\"name\": \"my-app\"}" },
    {
      "path": "tsconfig.json",
      "content": "{\"compilerOptions\": {\"strict\": true}}"
    }
  ]
}

Local Development

git clone <repo-url>
cd bitbucket-mcp-server
npm install
npm run build
npm start

Notes

• Uses Bitbucket Cloud API at https://api.bitbucket.org/2.0
• Authentication: Basic auth with ATLASSIAN_EMAIL + ATLASSIAN_API_TOKEN
• Stdio transport only (no HTTP port)
• Jira ticket references are automatically extracted from commit messages and PR descriptions
• Protected branches (main, master, develop, dev) cannot be deleted