Bitbucket
The Bitbucket connector lets AI agents explore repositories, review pull requests, browse pipelines, and read source files — all via the Bitbucket Cloud REST API using OAuth 2.0. Your credentials are stored encrypted in MCPGate's vault and are never exposed to the AI client.
Required scopes#
MCPGate requests the following OAuth scopes when you connect a Bitbucket account.
| Scope | Purpose |
|---|---|
| repository | Read repositories, branches, and file contents |
| pullrequest | Read and list pull requests |
| pullrequest:write | Create pull requests |
| issue | Read issues |
| issue:write | Create issues |
| pipeline | Read pipeline runs |
Tool reference#
The Bitbucket connector exposes 11 tools: 9 read and 2 write.
| Tool | Category | Description |
|---|---|---|
| bitbucket_list_repos | read | List Bitbucket repositories for the authenticated user |
| bitbucket_get_repo | read | Get a specific Bitbucket repository by workspace and slug |
| bitbucket_list_prs | read | List pull requests for a Bitbucket repository |
| bitbucket_get_pr | read | Get a specific pull request by repository and PR ID |
| bitbucket_list_issues | read | List issues for a Bitbucket repository |
| bitbucket_list_pipelines | read | List pipelines for a Bitbucket repository |
| bitbucket_read_file | read | Read a file from a Bitbucket repository |
| bitbucket_search_code | read | Search for code in a Bitbucket workspace |
| bitbucket_list_branches | read | List branches for a Bitbucket repository |
| bitbucket_create_pr | write | Create a new pull request in a Bitbucket repository |
| bitbucket_create_issue | write | Create a new issue in a Bitbucket repository |
No delete tools
Common guardrail recipes#
Read-only access#
Enable only the nine read tools and deny bitbucket_create_pr and bitbucket_create_issue. Ideal for code-review agents and pipeline dashboards.
Restrict to specific repositories#
Apply the allow_values template to bitbucket_create_pr and bitbucket_create_issue. Target the repo_slug field and provide a list of slug values the agent is permitted to write to.
Pipeline monitoring only#
Enable only bitbucket_list_repos, bitbucket_list_pipelines, and bitbucket_list_branches. Deny all other tools. This scopes the agent to CI/CD visibility with no code or PR access.
Troubleshooting#
- Workspace vs. username — Bitbucket Cloud uses workspace slugs in API paths. For personal accounts the workspace slug matches the username. For team workspaces it is the workspace slug visible in the Bitbucket settings.
- Issues not available — Bitbucket issue tracking must be enabled on the repository. If
bitbucket_list_issuesreturns an error, navigate to Repository settings → Features and enable issue tracking. - Code search limited —
bitbucket_search_codesearches within the default branch of repositories in the workspace. Cross-branch code search is not supported by the Bitbucket Cloud API.