# aashari/mcp-server-atlassian-bitbucket [Health: Active]

**Category:** 🔄 Version Control  
**Repository:** https://github.com/aashari/mcp-server-atlassian-bitbucket  
**GitHub Stars:** 161  
**npm Downloads (last month):** 17156  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/aashari-mcp-server-atlassian-bitbucket

## Description
Atlassian Bitbucket Cloud integration. Enables AI systems to interact with repositories, pull requests, workspaces, and code in real time.

## Tools
Capabilities this server exposes over MCP:

- **bb_get** — 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_post** — 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_put** — 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_patch** — 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_delete** — 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_clone** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server-atlassian-bitbucket": {
    "command": "npx",
    "args": ["-y","@aashari/mcp-server-atlassian-bitbucket"],
    "env": {
      "ATLASSIAN_USER_EMAIL": "",
      "ATLASSIAN_API_TOKEN": "",
      "ATLASSIAN_BITBUCKET_USERNAME": "",
      "ATLASSIAN_BITBUCKET_APP_PASSWORD": "",
      "BITBUCKET_DEFAULT_WORKSPACE": ""
    }
  }
}
```

**Requires environment variables:** `ATLASSIAN_USER_EMAIL`, `ATLASSIAN_API_TOKEN`, `ATLASSIAN_BITBUCKET_USERNAME`, `ATLASSIAN_BITBUCKET_APP_PASSWORD`, `BITBUCKET_DEFAULT_WORKSPACE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What aashari/mcp-server-atlassian-bitbucket MCP server does

The aashari/mcp-server-atlassian-bitbucket MCP server gives MCP-compatible assistants access to Bitbucket Cloud repositories, workspaces, branches, commits, source files, pull requests, comments, and diffs. Rather than exposing separate tools for every Bitbucket resource, it provides generic operations mapped to HTTP methods: `bb_get`, `bb_post`, `bb_put`, `bb_patch`, and `bb_delete`. A sixth tool, `bb_clone`, copies a repository to a local filesystem location.

The API tools can read any Bitbucket Cloud endpoint supported by the server and can create or modify resources when the supplied Bitbucket credentials have the required permissions. Examples include creating or merging a pull request, adding or editing comments, approving a pull request, changing repository metadata, managing branch restrictions, and deleting resources. Destructive operations such as deleting a repository are available, so client-side safeguards may be appropriate.

## How it works

Each API request takes a path beginning with `/`; the server adds the Bitbucket REST API `/2.0` prefix automatically. Optional query parameters include pagination, filtering, sorting, and sparse field selection. Responses use TOON by default, with JSON available through the `outputFormat` parameter.

The `jq` parameter filters or reshapes returned data before it is sent to the client. The provided guidance recommends using it on normal requests because unfiltered Bitbucket responses can contain substantial metadata. For unfamiliar endpoints, first retrieve one item without a filter to inspect its shape, then add a focused expression for later calls. Pagination can also be limited with `pagelen`, such as requesting a single workspace while discovering the schema.

The `bb_clone` operation accepts a repository slug and absolute target path. It prefers SSH when configured and falls back to HTTPS when SSH is unavailable. Local cloning therefore also depends on the machine’s repository access setup.

## Setup and configuration

The aashari/mcp-server-atlassian-bitbucket MCP server runs with Node.js 18 or newer and is distributed as the npm package `@aashari/mcp-server-atlassian-bitbucket`. The documented MCP configuration uses STDIO, commonly launched with `npx -y`.

For new configurations, provide `ATLASSIAN_USER_EMAIL` and `ATLASSIAN_API_TOKEN`, using the email associated with the Atlassian account. The material also documents the legacy pair `ATLASSIAN_BITBUCKET_USERNAME` and `ATLASSIAN_BITBUCKET_APP_PASSWORD`; app passwords are identified as deprecated and scheduled for removal in June 2026. Scoped tokens need Bitbucket repository and workspace scopes for read access, with pull-request scope included for full functionality. Write actions additionally require suitable permissions.

A system-wide configuration may define `BITBUCKET_DEFAULT_WORKSPACE`. Claude Desktop configuration places the server command and credentials under an MCP server entry; other MCP clients can use the same STDIO approach if they support it.

## Tools and capabilities

- `bb_get`: Read Bitbucket data, including workspaces, repositories, branches, commits, source files, pull requests, comments, and diffs.
- `bb_post`: Create resources or invoke supported actions such as creating, approving, requesting changes on, or merging pull requests.
- `bb_put`: Replace resources, including repository metadata and selected branch restriction or file operations.
- `bb_patch`: Partially update pull requests, reviewers, repositories, and comments.
- `bb_delete`: Remove resources, decline pull requests, remove approvals, or delete comments and repositories.
- `bb_clone`: Clone a repository locally through SSH or HTTPS fallback.

The aashari/mcp-server-atlassian-bitbucket MCP server is suited to repository investigation, pull-request workflows, branch comparisons, and agent-driven Bitbucket administration. It targets Bitbucket Cloud rather than Bitbucket Server or Data Center.

## Limitations and notes

Credentials and Bitbucket permissions determine which operations succeed. App passwords are a legacy option and should not be selected for new deployments where scoped API tokens are available. File uploads through the PUT interface use multipart form data and are described as more complex than metadata updates. Most delete endpoints return `204 No Content`, so successful deletion may produce no response body. Filtering and pagination should be used deliberately to avoid returning unnecessarily large responses.

_Full upstream README: https://allmcps.com/mcp/aashari-mcp-server-atlassian-bitbucket/readme_