# Bitbucket setup for PopMCP You paste one value into PopMCP: an Atlassian API token with scopes for Bitbucket. Then you pick the workspace it should work in. - Auth: API credentials - Setup time: 3 min - API base URL: https://api.bitbucket.org/2.0 - Credentials screen: https://id.atlassian.com/manage-profile/security/api-tokens - Provider docs: https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/ ## Before you begin - A Bitbucket Cloud account on bitbucket.org that belongs to at least one workspace. Bitbucket Data Center is not supported - Access to your Atlassian account settings at id.atlassian.com: if you sign in with a password or a third-party login, Atlassian may email a one-time code before it lets you create a token - Permission to create API tokens. An organization admin can block them for managed accounts through an authentication policy - Admin rights on the workspace or repository only for admin work: webhooks, branch restrictions, permissions and deploy keys ## Get your credentials ### 1. Open API tokens in your Atlassian account Go to `id.atlassian.com`, open Security and click Create and manage API tokens, or use the direct link. Bitbucket uses your Atlassian account's tokens: app passwords stopped working in 2026. Screen: https://id.atlassian.com/manage-profile/security/api-tokens ### 2. Name the token and set its expiry Click Create API token with scopes. Name it `PopMCP`, choose an expiry date (at most a year from today) and click Next. When the token expires, the connection stops working until you paste a new one. Screen: https://id.atlassian.com/manage-profile/security/api-tokens ### 3. Choose Bitbucket as the app Select Bitbucket in the list of apps and click Next. A token made for Jira or Confluence does not work with Bitbucket. Screen: https://id.atlassian.com/manage-profile/security/api-tokens ### 4. Tick the scopes Tick what the AI should be able to do, then click Next. For everyday work tick `read:repository:bitbucket`, `write:repository:bitbucket`, `read:pullrequest:bitbucket`, `write:pullrequest:bitbucket`, `read:pipeline:bitbucket`, `write:pipeline:bitbucket`, `read:workspace:bitbucket`, `read:project:bitbucket` and `read:user:bitbucket`. Add `read:webhook:bitbucket` and `write:webhook:bitbucket` for event triggers, and the `admin:` and `delete:` scopes only if the AI should change settings or delete things. For read-only use tick only the `read:` scopes. A scope never includes another: `write:repository:bitbucket` does not give read access by itself. Screen: https://id.atlassian.com/manage-profile/security/api-tokens ### 5. Create the token and copy it Check the summary, click Create token, then Copy the token. Tokens start with `ATATT`. Atlassian shows it only once, so paste it straight into PopMCP. Screen: https://id.atlassian.com/manage-profile/security/api-tokens ### 6. Paste it into PopMCP and choose the workspace In PopMCP, paste the token into API token and connect. PopMCP lists every workspace the token reaches: choose one, or several, each into its own PopMCP workspace. To use a repository, project or workspace access token instead (made under that resource's Settings, Access tokens), paste it and enter its workspace ID under More options. ## Fields PopMCP asks for - API token (apiToken) [required]: In your Atlassian account settings choose Security, then Create and manage API tokens, then Create API token with scopes. Name it, set an expiry, choose Bitbucket, tick the scopes, create it and copy it (it is shown once). Stored encrypted. - Workspace (only for an access token) (tokenWorkspace): Leave this empty for an API token: your workspaces are listed for you. For a repository, project or workspace access token, enter its workspace ID or paste a link to the repository. ## Verify PopMCP lists the workspaces the token reaches, and after you choose one the connection shows as Verified, labelled with the workspace name, with notes saying who it acts as and your role there. Asking the AI for open pull requests returns real pull request ids and titles. ## Troubleshooting ### "Bitbucket did not accept this token." Cause: The token expired or was revoked, was copied incompletely, or was made with Create API token (no scopes), which Bitbucket refuses. Fix: Create a new token with **Create API token with scopes**, choose **Bitbucket**, tick the scopes and paste the whole token. ### "That is a Bitbucket app password." Cause: App passwords (starting ATBB) were switched off by Atlassian in 2026. Fix: Create an API token with scopes for Bitbucket instead and paste that. ### "This API token cannot list your workspaces" Cause: The token lacks `read:workspace:bitbucket`. Fix: Create a new token with that scope ticked, or open **More options** and enter the workspace ID (the part after bitbucket.org/ in your links). ### "This is a repository, project or workspace access token, which cannot list workspaces." Cause: Access tokens belong to one resource and cannot enumerate workspaces. Fix: Open **More options** and enter the token's workspace ID, or paste a link to the repository. ### "There is no Bitbucket workspace ... that this token can reach." Cause: The workspace ID is mistyped, or the token's account or resource has no access to it. Fix: Copy the workspace ID from a repository link: it is the part right after bitbucket.org/. ### Some tools answer 403 while others work Cause: The token lacks a scope those tools need, or your role in the workspace (member rather than admin) does not allow the action. Fix: The error names the missing scope. Token scopes cannot be edited: create a new token with it ticked and reconnect. ### Event triggers never fire Cause: Registering the workspace webhook needs the webhook scopes and a workspace admin. Fix: Reconnect with a token that has `read:webhook:bitbucket` and `write:webhook:bitbucket`, made by a workspace admin. --- Source: https://www.docs.popmcp.com/docs/integrations/bitbucket/