Quick Start

Get up and running in 2 minutes:

1. Get Your Bitbucket Credentials

IMPORTANT: Bitbucket App Passwords are being deprecated and will be removed by June 2026. We recommend using Scoped API Tokens for new setups.

Option A: Scoped API Token (Recommended - Future-Proof)

Bitbucket is deprecating app passwords. Use the new scoped API tokens instead:

1. Go to Atlassian API Tokens
2. Click "Create API token with scopes"
3. Select "Bitbucket" as the product
4. Choose the appropriate scopes:
   • For read-only access: repository, workspace
   • For full functionality: repository, workspace, pullrequest
5. Copy the generated token (starts with ATATT)
6. Use with your Atlassian email as the username

Option B: App Password (Legacy - Will be deprecated)

Generate a Bitbucket App Password (legacy method):

1. Go to Bitbucket App Passwords
2. Click "Create app password"
3. Give it a name like "AI Assistant"
4. Select these permissions:
   • Workspaces: Read
   • Repositories: Read (and Write if you want AI to create PRs/comments)
   • Pull Requests: Read (and Write for PR management)

2. Try It Instantly

# Set your credentials (choose one method)

# Method 1: Scoped API Token (recommended - future-proof)
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"  # Token starting with ATATT

# OR Method 2: Legacy App Password (will be deprecated June 2026)
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"

# List your workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

# List repositories in a workspace
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace"

# Get pull requests for a repository
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo/pullrequests"

# Get repository details with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo" --jq "{name: name, language: language}"

Connect to AI Assistants

For Claude Desktop Users

Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):

Option 1: Scoped API Token (recommended - future-proof)

{
  "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"
      }
    }
  }
}

Option 2: Legacy App Password (will be deprecated June 2026)

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
        "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Restart Claude Desktop, and you'll see the bitbucket server in the status bar.

For Other AI Assistants

Most AI assistants support MCP. You can either:

Option 1: Use npx (recommended - always latest version): Configure your AI assistant to run: npx -y @aashari/mcp-server-atlassian-bitbucket

Option 2: Install globally:

npm install -g @aashari/mcp-server-atlassian-bitbucket

Then configure your AI assistant to use the MCP server with STDIO transport.

Supported AI assistants:

• Claude Desktop (official support)
• Cursor AI
• Continue.dev
• Cline
• Any MCP-compatible client

Alternative: Configuration File

Create ~/.mcp/configs.json for system-wide configuration:

Option 1: Scoped API Token (recommended - future-proof)

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_scoped_api_token",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

Option 2: Legacy App Password (will be deprecated June 2026)

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
      "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

Alternative config keys: The system also accepts "atlassian-bitbucket", "@aashari/mcp-server-atlassian-bitbucket", or "mcp-server-atlassian-bitbucket" instead of "bitbucket".

Available Tools

This MCP server provides 6 generic tools that can access any Bitbucket API endpoint:

| Tool | Description | Parameters | |------|-------------|------------| | bb_get | GET any Bitbucket API endpoint (read data) | path, queryParams?, jq?, outputFormat? | | bb_post | POST to any endpoint (create resources) | path, body, queryParams?, jq?, outputFormat? | | bb_put | PUT to any endpoint (replace resources) | path, body, queryParams?, jq?, outputFormat? | | bb_patch | PATCH any endpoint (partial updates) | path, body, queryParams?, jq?, outputFormat? | | bb_delete | DELETE any endpoint (remove resources) | path, queryParams?, jq?, outputFormat? | | bb_clone | Clone a repository locally | workspaceSlug?, repoSlug, targetPath |

Tool Parameters

All API tools support these common parameters:

• path (required): API endpoint path starting with / (the /2.0 prefix is added automatically)
• queryParams (optional): Key-value pairs for query parameters (e.g., {"pagelen": "25", "page": "2"})
• jq (optional): JMESPath expression to filter/transform the response - highly recommended to reduce token costs
• outputFormat (optional): "toon" (default, 30-60% fewer tokens) or "json"
• body (required for POST/PUT/PATCH): Request body as JSON object

Common API Paths

All paths automatically have /2.0 prepended. Full Bitbucket Cloud REST API 2.0 reference: https://developer.atlassian.com/cloud/bitbucket/rest/

Workspaces & Repositories:

• /workspaces - List all workspaces
• /repositories/{workspace} - List repos in workspace
• /repositories/{workspace}/{repo} - Get repo details
• /repositories/{workspace}/{repo}/refs/branches - List branches
• /repositories/{workspace}/{repo}/refs/branches/{branch_name} - Get/delete branch
• /repositories/{workspace}/{repo}/commits - List commits
• /repositories/{workspace}/{repo}/commits/{commit} - Get commit details
• /repositories/{workspace}/{repo}/src/{commit}/{filepath} - Get file content

Pull Requests:

• /repositories/{workspace}/{repo}/pullrequests - List PRs (GET) or create PR (POST)
• /repositories/{workspace}/{repo}/pullrequests/{id} - Get/update/delete PR
• /repositories/{workspace}/{repo}/pullrequests/{id}/diff - Get PR diff
• /repositories/{workspace}/{repo}/pullrequests/{id}/comments - List/add PR comments
• /repositories/{workspace}/{repo}/pullrequests/{id}/approve - Approve PR (POST) or remove approval (DELETE)
• /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes - Request changes (POST)
• /repositories/{workspace}/{repo}/pullrequests/{id}/merge - Merge PR (POST)
• /repositories/{workspace}/{repo}/pullrequests/{id}/decline - Decline PR (POST)

Comparisons:

• /repositories/{workspace}/{repo}/diff/{source}..{destination} - Compare branches/commits

Other Resources:

• /repositories/{workspace}/{repo}/issues - List/manage issues
• /repositories/{workspace}/{repo}/downloads - List/manage downloads
• /repositories/{workspace}/{repo}/pipelines - Access Bitbucket Pipelines
• /repositories/{workspace}/{repo}/deployments - View deployments

TOON Output Format

What is TOON? Token-Oriented Object Notation is a format optimized for LLMs that reduces token consumption by 30-60% compared to JSON. It uses tabular arrays and minimal syntax while preserving all data.

Default behavior: All tools return TOON format by default. You can override this with outputFormat: "json" if needed.

Example comparison:

JSON (verbose):
{
  "values": [
    {"name": "repo1", "slug": "repo-1"},
    {