Unify AI Interaction with Your Bitbucket Instance

Revolutionize your software development lifecycle by natively embedding large language models (LLMs) like Claude or Cursor directly into your Bitbucket data streams. Achieve immediate code comprehension, automated quality assurance checks, and significant acceleration of version control tasks.

Core Capabilities

• Contextual Code Querying: "What functional changes define the HEAD of my primary development branch?"
• Merge Request (PR) Triage: "List all pending PRs awaiting sign-off from the security team."
• Source Code Indexing & Retrieval: "Locate every file utilizing the deprecated Logger utility across the entire project structure."
• Delta Analysis: "Contrast the modifications between the staging branch and the production baseline."
• PR Lifecycle Management: "Initiate a new pull request merging topic-branch-xyz into develop."
• Automated Notification: "Post the automated test suite report summary as a comment on PR number 123."

Target Audience

• Engineering Practitioners: Seeking AI-powered assistance for code inspection and repository maintenance.
• Project Governance Leaders: Requiring rapid status aggregation on feature delivery and PR throughput.
• Infrastructure & Release Teams: Automating intricate branch promotions and operational scripts.
• Any User: Aiming to interact with Bitbucket via conversational interfaces.

Initial Setup

Deploying the connection takes under two minutes:

1. Authentication Credential Acquisition

🚨 CRITICAL NOTICE: Bitbucket App Passwords face scheduled obsolescence (End-of-Life projected June 2026). New deployments must utilize modern, Scoped API Tokens.

Method A: Scoped API Token (Preferred - Future-Resilient)

Replace legacy App Passwords with scoped tokens:

1. Navigate to Atlassian Security Token Portal
2. Select "Create API token with scopes"
3. Specify "Bitbucket" as the target product context.
4. Assign granular permissions:
   • Read-Only Access: Select repository and workspace permissions.
   • Full Read/Write Access: Select repository, workspace, and pullrequest permissions.
5. Securely record the generated token (it begins with ATATT).
6. Use your registered Atlassian email address as the authentication username.

Method B: App Password (Legacy - Deprecation Imminent)

Generate a traditional Bitbucket App Password: 1. Access Bitbucket Account Settings for App Passwords 2. Initiate creation of a new password, labeling it appropriately (e.g., "LLM Connector"). 3. Configure required permissions: * Workspaces: Grant Read access. * Repositories: Grant Read (and Write, if AI needs to modify code or branches). * Pull Requests: Grant Read (and Write for PR lifecycle actions).

2. Immediate Verification

Execute the following commands in your terminal (substituting your actual credentials):

# Define authentication variables (use one pair based on Method A or B)

# Option 1: Scoped Token (Recommended)
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_scoped_api_token_starting_with_ATATT"

# OR Option 2: Legacy App Password
export ATLASSIAN_BITBUCKET_USERNAME="your_bitbucket_login"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_legacy_password"

# Verify connectivity by listing organizational units
npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

# Retrieve repository manifest for a specific unit
npx -y @aashari/mcp-server-atlassian-bitbucket ls-repos --workspace-slug team-slug-name

# Query metadata for an individual code base
npx -y @aashari/mcp-server-atlassian-bitbucket get-repo --workspace-slug team-slug-name --repo-slug project-identifier

AI Assistant Integration

Integration with Claude Desktop Client

Incorporate the server settings into your local Claude configuration file (~/.claude/claude_desktop_config.json):

Configuration A: Scoped API Token (Recommended)

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

Configuration B: Legacy App Password

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

Ensure Claude Desktop is restarted to activate the "🔗 bitbucket" status indicator.

For Other MCP-Compliant Agents

Install the server globally via npm for system-wide accessibility:

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

Subsequently, configure your chosen agent to communicate with this server instance via the Standard Input/Output (STDIO) transport mechanism.

Persistent Configuration Alternative

Define global settings within ~/.mcp/configs.json:

Config A: Scoped Token Persistence

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

Config B: Legacy Password Persistence

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

Alias Flexibility: The key identifier can also be referenced as atlassian-bitbucket, @aashari/mcp-server-atlassian-bitbucket, or the full package name.

Practical Interaction Scenarios

🔍 Repository Exploration

AI Prompts: - "Generate a catalog of all active codebases within my default organizational unit." - "Retrieve the manifest file structure for the 'platform-service' repository." - "Display the chronological sequence of commits applied to the 'release-candidate' branch." - "Fetch the file content of config/settings.yaml as it exists on the master branch."

📋 Merge Request Oversight

AI Prompts: - "Identify all pull requests currently awaiting approval from senior reviewers." - "Analyze PR ID 42, detailing all introduced code changes and associated comments." - "Draft a new PR originating from dev-task-77 targeting the main branch." - "Append the results summary from the latest CI run to the discussion thread of PR #15." - *"Execute approval on pull request number 33, assuming all checks pass."

🔧 Branch & Code Manipulation

AI Prompts: - "Provide a side-by-side diff comparing my current feature branch state against the base branch." - "Provision a new branch named emergency-fix-2024 initialized from the current stable tag." - "Enumerate all branches currently active within the 'user-profile-service' project." - "Calculate the line-by-line divergence between commit hash abc123xyz and commit hash def456uvw."

🔎 Discovery and Indexing

AI Prompts: - "Scan all Python source files for instances of the string 'insecure_hash_algorithm'." - "Filter repositories based on open PRs that reference Jira ticket 'LOGIN-501'." - "List repositories belonging to the 'mobile-client' project group." - "Identify all files within the codebase built using the Vue.js framework."

Troubleshooting Common Failures

Errors: "Authentication Failure" or HTTP 403

1. Authentication Paradigm: Ensure consistency. Are you using Email + API Token (Atlassian-wide) or Username + App Password (Bitbucket-specific)?

2. For App Passwords (Method B):

   • Revisit App Password Management.
   • Confirm granular permissions are correctly granted for Workspaces (Read), Repositories (Read/Write), and Pull Requests (Read/Write).

3. For Scoped API Tokens (Recommended):

   • Validate token activity via the Atlassian Portal.
   • Verify the configuration file reflects the latest token and email: json { "@aashari/mcp-server-atlassian-bitbucket": { "environments": { "ATLASSIAN_USER_EMAIL": "your.email@company.com", "ATLASSIAN_API_TOKEN": "ATATT3xFfGF0..." } } }

4. Credential Testing: Run a basic command to isolate the auth issue: bash npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

Errors: "Organizational Unit Not Found" or "Codebase Identifier Missing"

1. Slug Verification: Use the listing command to confirm the exact identifier: bash npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

2. URL Mapping: The slug must match the identifier found in the web URL:

   • Example URL: https://bitbucket.org/my-internal-team/service-api
   • Organizational Slug: my-internal-team
   • Repository Slug: service-api

Error: "Default Workspace Undefined"

Specify a preferred default to streamline subsequent command execution:

export BITBUCKET_DEFAULT_WORKSPACE="preferred-team-slug"

Issues with Claude Desktop Synchronization

1. Apply a Restart: Always restart the Claude Desktop application after modifying its configuration file.
2. Check Status Indicator: Look for the "🔗 bitbucket" icon in the application's footer or status bar.
3. Verify Path Location: Confirm the file is placed in the correct system directory:
   • Linux/macOS: ~/.claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

Seeking Further Assistance

If resolution remains elusive: 1. Execute a simple diagnostic command to confirm server functionality. 2. Consult existing community reports at the Project GitHub Issues Tracker. 3. Submit a new issue detailing the specific error message and your environment parameters.

FAQs

Required Access Levels?

Scoped Tokens (Recommended): - The associated Atlassian user must have necessary entitlements. - Token must possess repository, workspace scopes. Include pullrequest scope for modification capabilities.

App Passwords (Legacy): - Viewing: Read access for Workspaces, Repositories, and Pull Requests. - Modifying: Write access required for Repositories (branch creation) and Pull Requests (approvals/comments).

Private Repository Compatibility?

Affirmative. Access is granted based on the permissions conferred to the supplied App Password or API Token.

Is setting a default workspace mandatory?

No, but highly advisable. Set the BITBUCKET_DEFAULT_WORKSPACE environment variable or configuration entry to omit repeated specification.

Supported AI Environments?

This server adheres to the Model Context Protocol (MCP) and integrates with: - Claude Desktop - Cursor AI - Continue.dev - Other MCP-compatible tools.

Data Privacy Assurance

Security is paramount: - Execution occurs entirely on the local host. - Utilization of your private credentials for access. - No transmission of your proprietary data to any external service provider.

Multi-Account Support?

Currently, one set of credentials per active instance. Managing separate Bitbucket accounts requires distinct configuration setups.

Support Channels

To obtain assistance: 1. Review the comprehensive troubleshooting guides above. 2. Consult the primary documentation repository: github.com/aashari/mcp-server-atlassian-bitbucket 3. File bugs or request enhancements via the Issue Tracker. 4. Engage in general discussion threads.

---

Engineered to enhance AI-driven interaction with Atlassian development tools.

WIKIPEDIA CONTEXT: Corporate oversight mechanisms encompass a diverse array of methodologies, software solutions, analytical frameworks, and procedural mandates employed by enterprises to effectively navigate dynamic market conditions, maintain competitive differentiation, and systematically elevate overall operational efficacy. These mechanisms can be categorized based on functional domains such as forecasting, workflow governance, archival integrity, personnel management, and strategic validation. Modern organizational toolsets are undergoing rapid transformation fueled by exponential technological progress, presenting managers with the challenge of discerning optimal solutions for specific corporate contexts. Success hinges not on adopting the newest technology blindly, but rather on the careful selection and subsequent tailoring of tools to align precisely with unique institutional requirements, rather than forcing organizational structure to conform to standardized software paradigms.