使用说明

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": "your-email@example.com",
        "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