Verified MCP server: Bitbucket
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Bitbucket MCP server connects an AI assistant to Bitbucket Cloud, giving it five HTTP verbs it can point at any path in the Bitbucket REST API, plus one tool that clones a repository to a folder on your Mac. It is a community project by one developer, aashari, not an Atlassian product, and npm records 3,370 downloads of it in the last week. Its credential is a pair of environment variables: your Atlassian account email and an API token scoped to Bitbucket, or the older Bitbucket app password pair the README says Atlassian planned to retire. We ran it with dummy credentials, so all 6 tools below were enumerated live from a real tools/list answer while no Bitbucket account was touched. The one tool call we made, a read of /workspaces, came back with the exact HTTP 401 the server returns when Bitbucket refuses the credentials, and that reply is printed further down, word for word. An authenticated call is still open: it waits on a real token. [1][3][2][4]
Verification
Method
We spawned the server with npx over stdio with a dummy pair of legacy Bitbucket credentials in ATLASSIAN_BITBUCKET_USERNAME and ATLASSIAN_BITBUCKET_APP_PASSWORD, completed the MCP initialize handshake, and called tools/list: it answered with all 6 tools, and the table below is that answer, word for word. We then made one real tool call, bb_get on the path /workspaces with a page length of one, and the reply below is what came back: the server reached Bitbucket, Bitbucket refused the credentials, and the tool returned an HTTP 401 carrying the server's own AUTH_INVALID payload. A second run on the same Mac on the same day, started with no environment variables at all, listed the same 6 tools and failed the same call with an AUTH_MISSING error instead, which is quoted in the troubleshooting section. The tools are therefore enumerated live and both errors are real output, while a successful authenticated call still waits on a real Atlassian API token.
Startup banner
[21:07:57] [INFO] [index.ts@main] Starting server with STDIO transport [21:07:57] [INFO] [index.ts] Starting MCP server in stdio mode with @aashari/mcp-server-atlassian-bitbucket v3.1.0 [21:07:57] [INFO] [index.ts@startServer] Starting MCP server initialization... [21:07:57] [INFO] [index.ts@startServer] Initializing Bitbucket MCP server v3.1.0 [21:07:57] [INFO] [index.ts@startServer] Registering MCP tools... [21:07:57] [INFO] [index.ts@startServer] All tools registered successfully [21:07:57] [INFO] [index.ts@startServer] Using STDIO transport for MCP communication [21:07:57] [INFO] [index.ts@startServer] MCP server started successfully on STDIO transport [21:07:57] [INFO] [index.ts@main] Server is now running
One real tool call
tools/call bb_get {"path": "/workspaces", "queryParams": {"pagelen": "1"}}Error: Access denied for api. Verify your credentials and permissions. Ensure your Bitbucket API token/app password has sufficient privileges and hasn't expired. If using a workspace/repository name, check that it's spelled correctly.
HTTP Status: 401
Raw API Response:
{
"name": "McpError",
"type": "AUTH_INVALID",
"statusCode": 401,
"originalError": "",
"errorType": "AUTHENTICATION_REQUIRED"
}Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 6 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| bb_getpath*queryParamsjqoutputFormat | Read any Bitbucket data. Returns TOON format by default (30-60% fewer tokens than JSON). **IMPORTANT - Cost Optimization:** - ALWAYS use `jq` param to filter response fields. Unfiltered responses are very expensive! - Use `pagelen` query param to restrict result count (e.g., `pagelen: "5"`) - If unsure about available fields, first fetch ONE item with `pagelen: "1"` and NO jq filter to explore the schema, then use jq in subsequent calls **Schema Discovery Pattern:** 1. First call: `path: "/workspaces", queryParams: {"pagelen": "1"}` (no jq) - explore available fields 2. Then use: `jq: "values[*].{slug: slug, name: name, uuid: uuid}"` - extract only what you need **Output format:** TOON (default, token-efficient) or JSON (`outputFormat: "json"`) **Common paths:** - `/workspaces` - list workspaces - `/repositories/{workspace}` - list repos in workspace - `/repositories/{workspace}/{repo}` - get repo details - `/repositories/{workspace}/{repo}/pullrequests` - list PRs - `/repositories/{workspace}/{repo}/pullrequests/{id}` - get PR details - `/repositories/{workspace}/{repo}/pullrequests/{id}/comments` - list PR comments - `/repositories/{workspace}/{repo}/pullrequests/{id}/diff` - get PR diff - `/repositories/{workspace}/{repo}/refs/branches` - list branches - `/repositories/{workspace}/{repo}/commits` - list commits - `/repositories/{workspace}/{repo}/src/{commit}/{filepath}` - get file content - `/repositories/{workspace}/{repo}/diff/{source}..{destination}` - compare branches/commits **Query params:** `pagelen` (page size), `page` (page number), `q` (filter), `sort` (order), `fields` (sparse response) **Example filters (q param):** `state="OPEN"`, `source.branch.name="feature"`, `title~"bug"` **JQ examples:** `values[*].slug`, `values[0]`, `values[*].{name: name, uuid: uuid}` The `/2.0` prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/ |
| bb_postpath*queryParamsjqoutputFormatbody* | Create Bitbucket resources. Returns TOON format by default (token-efficient). **IMPORTANT - Cost Optimization:** - Use `jq` param to extract only needed fields from response (e.g., `jq: "{id: id, title: title}"`) - Unfiltered responses include all metadata and are expensive! **Output format:** TOON (default) or JSON (`outputFormat: "json"`) **Common operations:** 1. **Create PR:** `/repositories/{workspace}/{repo}/pullrequests` body: `{"title": "...", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}` 2. **Add PR comment:** `/repositories/{workspace}/{repo}/pullrequests/{id}/comments` body: `{"content": {"raw": "Comment text"}}` 3. **Approve PR:** `/repositories/{workspace}/{repo}/pullrequests/{id}/approve` body: `{}` 4. **Request changes:** `/repositories/{workspace}/{repo}/pullrequests/{id}/request-changes` body: `{}` 5. **Merge PR:** `/repositories/{workspace}/{repo}/pullrequests/{id}/merge` body: `{"merge_strategy": "squash"}` (strategies: merge_commit, squash, fast_forward) The `/2.0` prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/ |
| bb_putpath*queryParamsjqoutputFormatbody* | Replace Bitbucket resources (full update). Returns TOON format by default. **IMPORTANT - Cost Optimization:** - Use `jq` param to extract only needed fields from response - Example: `jq: "{uuid: uuid, name: name}"` **Output format:** TOON (default) or JSON (`outputFormat: "json"`) **Common operations:** 1. **Update repository:** `/repositories/{workspace}/{repo}` body: `{"description": "...", "is_private": true, "has_issues": true}` 2. **Create/update file:** `/repositories/{workspace}/{repo}/src` Note: Use multipart form data for file uploads (complex - prefer PATCH for metadata) 3. **Update branch restriction:** `/repositories/{workspace}/{repo}/branch-restrictions/{id}` body: `{"kind": "push", "pattern": "main", "users": [{"uuid": "..."}]}` The `/2.0` prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/ |
| bb_patchpath*queryParamsjqoutputFormatbody* | Partially update Bitbucket resources. Returns TOON format by default. **IMPORTANT - Cost Optimization:** Use `jq` param to filter response fields. **Output format:** TOON (default) or JSON (`outputFormat: "json"`) **Common operations:** 1. **Update PR title/description:** `/repositories/{workspace}/{repo}/pullrequests/{id}` body: `{"title": "New title", "description": "Updated description"}` 2. **Update PR reviewers:** `/repositories/{workspace}/{repo}/pullrequests/{id}` body: `{"reviewers": [{"uuid": "{user-uuid}"}]}` 3. **Update repository properties:** `/repositories/{workspace}/{repo}` body: `{"description": "New description"}` 4. **Update comment:** `/repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}` body: `{"content": {"raw": "Updated comment"}}` The `/2.0` prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/ |
| bb_deletepath*queryParamsjqoutputFormat | Delete Bitbucket resources. Returns TOON format by default. **Output format:** TOON (default) or JSON (`outputFormat: "json"`) **Common operations:** 1. **Delete branch:** `/repositories/{workspace}/{repo}/refs/branches/{branch_name}` 2. **Delete PR comment:** `/repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}` 3. **Decline PR:** `/repositories/{workspace}/{repo}/pullrequests/{id}/decline` 4. **Remove PR approval:** `/repositories/{workspace}/{repo}/pullrequests/{id}/approve` 5. **Delete repository:** `/repositories/{workspace}/{repo}` (caution: irreversible) Note: Most DELETE endpoints return 204 No Content on success. The `/2.0` prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/ |
| bb_cloneworkspaceSlugrepoSlug*targetPath* | Clone a Bitbucket repository to your local filesystem using SSH (preferred) or HTTPS. Provide `repoSlug` and `targetPath` (absolute path). Clones into `targetPath/repoSlug`. SSH keys must be configured; falls back to HTTPS if unavailable. |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@aashari/mcp-server-atlassian-bitbucket"
],
"env": {
"ATLASSIAN_USER_EMAIL": "your.email@company.com",
"ATLASSIAN_API_TOKEN": "your_scoped_api_token"
}
}
}
}Replace both values with your own Atlassian account email and a Bitbucket-scoped API token, then quit and reopen Claude Desktop. The project README points at a different file, ~/.claude/claude_desktop_config.json; the path above is the one Anthropic documents for macOS, and it is the one that works. [9][4]
One command in your terminal:
claude mcp add bitbucket --env ATLASSIAN_USER_EMAIL=your.email@company.com --env ATLASSIAN_API_TOKEN=your_scoped_api_token -- npx -y @aashari/mcp-server-atlassian-bitbucket
Everything after the double dash is the exact command Claude Code will run, and each --env passes one credential to it. The older pair, ATLASSIAN_BITBUCKET_USERNAME and ATLASSIAN_BITBUCKET_APP_PASSWORD, is passed the same way and is what our own run used. [10][4]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@aashari/mcp-server-atlassian-bitbucket"
],
"env": {
"ATLASSIAN_USER_EMAIL": "your.email@company.com",
"ATLASSIAN_API_TOKEN": "your_scoped_api_token"
}
}
}
}Cursor picks the file up on restart. Prefer the file in your home folder: a token written into a project file is one commit away from being public, and this one reaches your repositories. [11][4]
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Bitbucket Command npx Arguments -y @aashari/mcp-server-atlassian-bitbucket Environment Variables ATLASSIAN_USER_EMAIL your.email@company.com ATLASSIAN_API_TOKEN your_scoped_api_token
The Arguments field splits on spaces, so keep it to exactly those two words. Both credentials go in Environment Variables, never in Arguments. If most of your work sits in one workspace, add a third row, BITBUCKET_DEFAULT_WORKSPACE, and the tools stop needing it spelled out every time. Click Test Connection first: a working server answers with its tool count, six for this one. [12][4]
No terminal needed
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Sign in to Bitbucket, then open id.atlassian.com/manage-profile/security/api-tokens and create an API token scoped to Bitbucket. The README asks for the repository and workspace scopes to read things, plus the pullrequest scope if you want the assistant to write to pull requests. Copy the token while it is on screen, because Atlassian does not show it again. This server works with Bitbucket Cloud only, not with a Bitbucket Server or Data Center install.
03
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
This server is a command, not a web address, so switch the form to Command (stdio). Name: Bitbucket. Command: npx. Arguments: -y @aashari/mcp-server-atlassian-bitbucket. That is the whole command; there are no folders or extra options to add.
05
Add two rows to Environment Variables: ATLASSIAN_USER_EMAIL with the email address of your Atlassian account, and ATLASSIAN_API_TOKEN with the token you just copied. A third row, BITBUCKET_DEFAULT_WORKSPACE set to your workspace name, saves you repeating it in every request later.
06
Click Test Connection: Routines starts the server and reports how many tools it found, six for this one. Then click Add Server. The tools work in chat right away, and to let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every Monday at 8:30, list the open pull requests in my main Bitbucket repository, note who opened each one, how many days it has been waiting and whether it has reviewers yet, and save the list as pr-triage.md with the oldest first.
Every Friday at 16:00, look at the pull requests merged into main this week in my Bitbucket repository, and write a short plain-English summary of what shipped, one line per change, saved as shipped-this-week.md.
Every Wednesday at 9:00, find the pull requests in my Bitbucket repository that have been open more than seven days with no new comments, and draft a short friendly message for each author asking whether it is still needed. Do not post anything, just save the drafts as pr-nudges.md.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
Error: Access denied for api. Verify your credentials and permissions. Ensure your Bitbucket API token/app password has sufficient privileges and hasn't expired. If using a workspace/repository name, check that it's spelled correctly.
HTTP Status: 401
Raw API Response:
{
"name": "McpError",
"type": "AUTH_INVALID",
"statusCode": 401,
"originalError": "",
"errorType": "AUTHENTICATION_REQUIRED"
}The fix
This is the reply our own sample call received, on purpose: we started the server with a dummy username and app password. It means the server ran, reached Bitbucket, and Bitbucket refused the credentials. Check three things. ATLASSIAN_USER_EMAIL has to be the email of the Atlassian account the token belongs to, not a Bitbucket display name. The token has to be pasted whole, with no line break in the middle. And it has to still be valid, since tokens expire and can be revoked. Create a fresh one, paste it in, and restart the server so it reads the new value.
What you see
Error: An unexpected error occurred while GET request api. Error details: Authentication credentials are missing
HTTP Status: 500
Raw API Response:
{
"name": "McpError",
"type": "AUTH_MISSING",
"errorType": "AUTHENTICATION_REQUIRED"
}The fix
We captured this by starting the server with no environment variables at all. It still started, still listed the same six tools, and only failed when a tool actually called Bitbucket, which is why a healthy tool count is not proof that your credentials arrived. If you see it, your client is not passing the variables through: in a JSON config, check the env block sits inside the server entry rather than beside it, and in Routines check the rows are in Environment Variables rather than appended to Arguments.
What you see
{
"message": "CHANGE-2770 - Functionality has been deprecated",
"detail": "Please read the changelog entry for more details.",
"data": { "announcement_url": "https://developer.atlassian.com/cloud/bitbucket/changelog#CHANGE-2770" }
}The fix
Bitbucket itself retired the cross-workspace listing endpoint, so a call to /workspaces now answers with an HTTP 410 no matter which client asks. This one is not our capture: a user reported it against this same version, 3.1.0, in open issue 230 on the project GitHub. Our own call to that path never got as far as the deprecation check, because Bitbucket rejected our dummy credentials first. Repository-scoped paths are unaffected, so name the workspace directly, as in /repositories/your-workspace, or set BITBUCKET_DEFAULT_WORKSPACE once and let the assistant fill it in.
What you see
Error: Access denied for api. Verify your credentials and permissions. Ensure your Bitbucket API token/app password has sufficient privileges and hasn't expired. HTTP Status: 403 Raw API Response: This endpoint does not support token-based authentication
The fix
Reads succeed and writes to a pull request fail, with Bitbucket saying in as many words that the endpoint does not accept token authentication. This is another user report, open issue 229 on the project GitHub, filed against the scoped Atlassian API token; we did not reproduce it, because our run had no working credentials at all. If it hits you, follow that issue rather than reaching for the older app password pair: the README says Atlassian planned to remove app passwords by June 2026, a date already behind us.
FAQ
It is a small program that connects an AI assistant to Bitbucket Cloud. Instead of one tool per Bitbucket action, it hands the assistant five HTTP verbs it can point at any path in the Bitbucket REST API, so the same handful of tools covers workspaces, repositories, pull requests, comments, branches, commits and file contents. A sixth tool clones a repository into a folder on your Mac. It runs as a local process started by npx and talks to your AI app over stdio, and it works with Bitbucket Cloud only, not with Bitbucket Server or Data Center. [1][4]
The running server exposes 6 tools: bb_get to read, bb_post to create, bb_put to replace, bb_patch to update in part, bb_delete to remove, and bb_clone to copy a repository to a local folder. The table above is the live tools/list output, word for word, including the long usage notes the server writes for the assistant, such as the common Bitbucket paths and the advice to always filter responses. Two things follow from that design. Older write-ups list dozens of named tools like list_repositories, which was true before the 2.0 rewrite collapsed them into these verbs, and an open issue asks for the per-tool control that change removed. And because the path is open-ended, an endpoint Bitbucket has since retired fails at Bitbucket rather than at this server, which is exactly the /workspaces problem in the troubleshooting section. [8][6]
Its reach is the reach of the token you give it, and nothing more. That cuts both ways. A token with read scopes on one workspace is a narrow connection, while a token that can write hands an AI assistant bb_put, bb_patch and bb_delete pointed at any path in your Bitbucket account, and the delete tool description above names deleting a repository as one of its own examples, marked irreversible. Two habits keep it sane: make a token for this one purpose with the smallest scopes that do the job, and add the pullrequest scope only when you actually want changes written. bb_clone deserves its own line, because it is the one tool that writes to your Mac rather than to Bitbucket: it runs a git clone into the folder you name. [4]
No. In Routines you fill in a few fields in Settings, paste your email and token into the Environment Variables field, and click Test Connection; the walkthrough above shows every click. Creating the token itself happens on the Atlassian website, not in a terminal. Claude Desktop and Cursor need a small JSON file edited once. Only Claude Code is terminal-first by nature. [12][9]
Yes, and this is the one real setup step. You need a Bitbucket Cloud account and two environment variables: ATLASSIAN_USER_EMAIL with your Atlassian account email, and ATLASSIAN_API_TOKEN with an API token scoped to Bitbucket, created at id.atlassian.com. The README documents an older pair as well, ATLASSIAN_BITBUCKET_USERNAME and ATLASSIAN_BITBUCKET_APP_PASSWORD, and states that Atlassian planned to remove app passwords by June 2026, so start with the token. Without credentials the server still starts and still lists all 6 tools, which is exactly what our run shows, and only the call to Bitbucket fails. One known gap to be aware of: reads work with a scoped token while some pull request writes are reported to be refused by Bitbucket as not supporting token authentication. [4][7]
No. It is maintained by one developer, aashari, on a personal GitHub account, and nothing in the package, the repository or the README claims an Atlassian affiliation. npm records 3,370 downloads in the last week and the repository has 160 stars, so it has real users, but support and updates come from one volunteer. The license is worth settling before it goes on a company laptop: npm and the package.json both declare ISC, while the repository carries no LICENSE file and GitHub detects no license at all, and an open issue asks the maintainer to clarify exactly that. [3][1][2][5]
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config and the credentials differs. It needs Node.js 18 or newer on the Mac that runs it, which is also what the npx command in every config above depends on. [9][10][11][12][4]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 3.1.0, published 2026-02-17; license field ISC; repository git+https://github.com/aashari/mcp-server-atlassian-bitbucket.git; single npm maintainer aashari.
[2]
3,370 downloads for the week 2026-07-27 to 2026-08-02.
[3]
160 stars, owner aashari is an individual user account, pushed 2026-03-06, default branch main, license field null with no LICENSE file at the repository root.
[4]
Source of the credential model (ATLASSIAN_USER_EMAIL with ATLASSIAN_API_TOKEN, the legacy username and app password pair, optional BITBUCKET_DEFAULT_WORKSPACE), the client config JSON, the repository and workspace scopes, the Node.js 18 requirement, the Bitbucket Cloud only limitation, and the statement that app passwords were to be removed by June 2026.
[5]
Open issue from a user evaluating the project for internal use, flagging that GitHub detects no license while npm declares ISC.
[6]
Open issue filed against version 3.1.0 in June 2026, quoting the CHANGE-2770 deprecation response Bitbucket now returns for the cross-workspace listing endpoint.
[7]
Open issue quoting the 403 and the Bitbucket message "This endpoint does not support token-based authentication"; reads succeed with the same scoped token.
[8]
Open issue title, read from the issue listing: before 2.0 the server exposed many individually named tools that could be toggled, which the generic verb tools replaced.
[9]
The official Claude Desktop quickstart: the macOS config file location and the mcpServers shape.
[10]
The claude mcp add syntax for local stdio servers, including --env.
[11]
[12]
How Routines runs one-click OAuth connectors and any MCP server.
This page describes Bitbucket as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines