Bitbucket MCP

An MCP server for Bitbucket Cloud. Use it from any MCP-capable client (Cursor, Claude Desktop, Codex, and others) to manage pull requests, branches, and repositories in natural language.

It targets the Bitbucket Cloud REST API at https://api.bitbucket.org/2.0 by default. You can point it at a Bitbucket Server / Data Center instance with BITBUCKET_BASE_URL, but only endpoints that match the Cloud API shape are guaranteed to work.

Prerequisites

• Node.js 24 or newer
• A Bitbucket Cloud account with access to the workspace you want to use

Installation

Run the published package directly with npx (recommended — no install step):

npx -y @inconcept-labs/bitbucket-mcp

Or install globally and run the bitbucket-mcp binary:

npm install -g @inconcept-labs/bitbucket-mcp
bitbucket-mcp

The server speaks MCP over stdio and is meant to be launched by an MCP client, not run by hand.

Setup

1. Create an Atlassian API token

This server authenticates with a scoped Atlassian API token. (Bitbucket Cloud app passwords are deprecated — new ones can no longer be created since 2025-09-09, and any remaining ones stop working on 2026-06-09.)

1. Sign in to Bitbucket, click your avatar (top-right) → Account settings.
2. Open the Security tab → Create and manage API tokens → Create API token with scopes.
3. Give the token a name and an expiry date, then select Bitbucket as the app.
4. Select these scopes:
   • read:repository:bitbucket
   • write:repository:bitbucket
   • read:pullrequest:bitbucket
   • write:pullrequest:bitbucket
   • admin:repository:bitbucket
5. Click Create token and copy the value immediately — Atlassian only displays it once.

2. Find your workspace slug and Atlassian email

• Workspace slug: the path segment in your Bitbucket URL — e.g. for https://bitbucket.org/acme-inc/some-repo, the slug is acme-inc. Use the slug, not the workspace display name.
• Atlassian email: the email address you sign in to Atlassian with. API tokens authenticate as email:token — your Bitbucket username will not work.

3. Environment variables

| Variable | Required | Description | | --------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | BITBUCKET_USERNAME | Yes | Your Atlassian account email (used as the Basic-auth username paired with the API token). | | BITBUCKET_APP_PASSWORD | Yes | Your Atlassian API token from step 1. The variable is named APP_PASSWORD for backward compatibility. | | BITBUCKET_WORKSPACE | Yes | Workspace slug from your Bitbucket URL. | | BITBUCKET_BASE_URL | No | API base URL. Defaults to https://api.bitbucket.org/2.0. Override only for Bitbucket Server / Data Center. | | BITBUCKET_MCP_ALLOW_DESTRUCTIVE_TOOLS | No | Set to true, 1, yes, or on to expose delete_branch and delete_pr_comment. Off by default — these tools are not registered unless you opt in. |

4. MCP client configuration

Add a server entry that runs the package with npx and passes the variables above. Example:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@inconcept-labs/bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "[email protected]",
        "BITBUCKET_APP_PASSWORD": "your_atlassian_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace_slug"
      }
    }
  }
}

Where this file lives

• Cursor: ~/.cursor/mcp.json, or Cursor → Settings → MCP
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

After saving, restart the MCP client so it picks up the new server.

Available tools

Repositories

| Tool | Description | | ------------------- | ----------------------------------------------------------- | | list_repositories | List repos in the workspace (supports search & pagination). |

Pull requests

| Tool | Description | | ------------------------- | --------------------------------------------------------------------------- | | list_pull_requests | List PRs filtered by state (OPEN / MERGED / DECLINED / SUPERSEDED). | | get_pull_request | Full PR details including participants and reviewers. | | create_pull_request | Open a new PR with optional reviewers. | | update_pull_request | Update title, description, or reviewers. | | merge_pull_request | Merge using merge_commit, squash, or fast_forward. | | decline_pull_request | Decline a PR with an optional message. | | add_pr_comment | Post a Markdown comment on a PR. | | get_diff | Fetch the unified diff (truncated for safety). | | list_pr_comments | List all comments on a PR. | | get_pr_comment | Get a specific comment. | | update_pr_comment | Update a comment. | | delete_pr_comment | Delete a comment (requires BITBUCKET_MCP_ALLOW_DESTRUCTIVE_TOOLS). | | resolve_pr_comment | Resolve a comment thread. | | reopen_pr_comment | Reopen a resolved comment thread. | | approve_pull_request | Approve a PR. | | unapprove_pull_request | Remove your approval. | | request_pr_changes | Request changes on a PR. | | list_pr_statuses | List commit / build statuses for a PR. | | list_default_reviewers | List default reviewers (auto-added to new PRs). | | get_default_reviewer | Get a specific default reviewer. | | add_default_reviewer | Add a user as default reviewer. | | remove_default_reviewer | Remove a user from default reviewers. |

Branches

| Tool | Description | | --------------- | ------------------------------------------------------------------- | | list_branches | List branches with optional name search. | | delete_branch | Delete a branch (requires BITBUCKET_MCP_ALLOW_DESTRUCTIVE_TOOLS). |

Example prompts

• "List all open PRs in the backend repo"
• "Create a PR from feature/auth to main: 'Add OAuth login'"
• "Show me the diff for PR #42"
• "Merge PR #42 using squash"
• "Decline PR #15 with message: not needed anymore"
• "Add a comment to PR #8: 'LGTM!'"

Troubleshooting

• Configuration error on startup — One or more required env vars are missing or empty. Set BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD, and BITBUCKET_WORKSPACE, then restart the MCP client.
• 401 Unauthorized — Most often one of:
  • BITBUCKET_USERNAME is your Bitbucket username instead of your Atlassian email — API tokens require the email.
  • The API token is wrong, expired, or was created without the scopes listed above.
  • You're still using a legacy app password — create an API token instead (app passwords are being phased out).
• 403 Forbidden — The token authenticates but is missing a scope for the tool you ran. Re-create the token and add the missing scope (e.g. write:pullrequest:bitbucket for merge/approve, write:repository:bitbucket for delete_branch).
• 404 Not Found for repos — BITBUCKET_WORKSPACE is wrong. Use the slug from the URL (e.g. acme-inc), not the workspace display name.
• Destructive tool not found — delete_branch and delete_pr_comment are not registered unless BITBUCKET_MCP_ALLOW_DESTRUCTIVE_TOOLS is set to a truthy value. Set it and restart the client.

Contributing

For development, project layout, testing, and release automation, see CONTRIBUTING.md.

Links

• Atlassian: Create an API token
• Atlassian: API token permissions

License

MIT