@jestay/bitbucket-mcp

MCP server for code review of Bitbucket Cloud pull requests: list PRs, read diffs, file contents and comments, and post review comments (general, inline on specific lines, or replies).

Tools

Tool	Description
list_pull_requests	List PRs of a repo, filtered by state (default OPEN)
get_pull_request	Full PR metadata: branches, commits, reviewers, approval status
get_pull_request_diff	Unified diff of the PR (plain text)
get_file_content	Raw file content at a branch/tag/commit
list_pull_request_comments	Existing PR comments (general and inline)
create_pull_request_comment	Post a comment: general, inline (file_path + line) or reply (parent_id)

Review workflow

By default the server ships MCP instructions telling the connected agent to review first and comment later: read the diff, consolidate all findings, present them to the user, and post only the comments the user explicitly approved. create_pull_request_comment carries the same warning in its description.

For unattended use (automation/CI), set BITBUCKET_YOLO=true to remove the approval gate and let the agent comment autonomously.

Requirements

• Node.js 20.6+
• An Atlassian API token (see below)

Creating the API token

Create an API token with scopes at https://id.atlassian.com/manage-profile/security/api-tokens, select Bitbucket as the app, and grant these scopes:

Scope	Used for
read:user:bitbucket	Authentication / identifying the token's user
read:workspace:bitbucket	Resolving the workspace in API routes
read:repository:bitbucket	Reading repository file contents (get_file_content)
read:pullrequest:bitbucket	Listing and reading PRs, diffs and comments
write:pullrequest:bitbucket	Posting review comments

No other scopes are needed — in particular, write:repository:bitbucket is NOT required (this server never pushes code).

Note: Atlassian App Passwords are deprecated — use API tokens.

Usage (npx)

No installation needed — any machine with Node 20.6+ can run it via npx.

.mcp.json (Claude Code) or claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@jestay/bitbucket-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "you@company.com",
        "BITBUCKET_API_TOKEN": "your_token_here",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add bitbucket \
  -e BITBUCKET_EMAIL=you@company.com \
  -e BITBUCKET_API_TOKEN=your_token_here \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y @jestay/bitbucket-mcp

Environment variables

Variable	Required	Description
BITBUCKET_EMAIL	Yes	Atlassian account email
BITBUCKET_API_TOKEN	Yes	Atlassian API token (scopes above)
BITBUCKET_WORKSPACE	No	Default workspace so tools don't need it per call
BITBUCKET_YOLO	No	Set to true/1 to disable the ask-before-commenting guidance (automation/CI)

Local development

pnpm install
pnpm build
cp .env.example .env   # then fill in the values
pnpm dev               # run from source (tsx)
pnpm start             # run the compiled build

pnpm dev and pnpm start load environment variables from a .env file in the project root. When registering the server in an MCP client, environment variables come from the client's own config instead and no .env file is needed. To register a local build, use node /absolute/path/to/bitbucket-mcp/dist/index.js as the command.

Project layout

src/
├── index.ts     # entry point
├── config.ts    # env-var configuration
├── client.ts    # HTTP client for the Bitbucket Cloud API 2.0 (auth lives here)
└── server.ts    # McpServer + tool registration