Name: Server Atlassian Bitbucket
Author: aashari

Connect AI to Your Bitbucket Repositories

Transform how you work with Bitbucket by connecting Claude, Cursor AI, and other AI assistants directly to your repositories, pull requests, and code. Get instant insights, automate code reviews, and streamline your development workflow.

What You Can Do

Ask AI about your code: "What's the latest commit in my main repository?"
Get PR insights: "Show me all open pull requests that need review"
Search your codebase: "Find all JavaScript files that use the authentication function"
Review code changes: "Compare the differences between my feature branch and main"
Manage pull requests: "Create a PR for my new-feature branch"
Automate workflows: "Add a comment to PR #123 with the test results"

Perfect For

Developers who want AI assistance with code reviews and repository management
Team Leads needing quick insights into project status and pull request activity
DevOps Engineers automating repository workflows and branch management
Anyone who wants to interact with Bitbucket using natural language

Requirements

Node.js 18.0.0 or higher
Bitbucket Cloud account (not Bitbucket Server/Data Center)
Authentication credentials: Scoped API Token (recommended) or App Password (legacy)

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:

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

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

Generate a Bitbucket App Password (legacy method):

Go to Bitbucket App Passwords
Click "Create app password"
Give it a name like "AI Assistant"
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"},
    {"name": "repo2", "slug": "repo-2"}
  ]
}

TOON (efficient):
values:
  name  | slug
  repo1 | repo-1
  repo2 | repo-2

Learn more: https://github.com/toon-format/toon

JMESPath Filtering

All tools support optional JMESPath (jq) filtering to extract specific data and reduce token costs further:

Important: Always use jq to filter responses! Unfiltered API responses can be very large and expensive in terms of tokens.

# Get just repository names
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace" \
  --jq "values[].name"

# Get PR titles and states (custom object shape)
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --jq "values[].{title: title, state: state, author: author.display_name}"

# Get first result only
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace" \
  --jq "values[0]"

# Explore schema with one item first, then filter
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/workspaces" \
  --query-params '{"pagelen": "1"}'

Common JMESPath patterns:

values[*].fieldName - Extract single field from all items
values[*].{key1: field1, key2: field2} - Create custom object shape
values[0] - Get first item only
values[:5] - Get first 5 items
values[?state=='OPEN'] - Filter by condition

Full JMESPath reference: https://jmespath.org

Real-World Examples

Explore Your Repositories

Ask your AI assistant:

"List all repositories in my main workspace"
"Show me details about the backend-api repository"
"What's the commit history for the feature-auth branch?"
"Get the content of src/config.js from the main branch"

Manage Pull Requests