Bitbucket MCP server

The MCP Server for Bitbucket allows you to connect AI assistants like Claude and Cursor AI directly to your Bitbucket repositories, enabling you to interact with your code, pull requests, and repositories using natural language commands. This integration streamlines your development workflow by providing AI-powered insights and automation.

Installation

Obtaining Bitbucket Credentials

Before installing, you'll need to set up your Bitbucket credentials. There are two authentication methods:

Scoped API Token (Recommended)

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

App Password (Legacy - Will be deprecated by June 2026)

1. Go to Bitbucket App Passwords
2. Click "Create app password"
3. Name it "AI Assistant"
4. Select permissions:
   • Workspaces: Read
   • Repositories: Read (and Write for creating PRs/comments)
   • Pull Requests: Read (and Write for PR management)

Quick Testing

To quickly test your setup:

# For Scoped API Token (recommended)
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"

# OR for Legacy App Password
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"

# List your workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

# List repositories in your workspace
npx -y @aashari/mcp-server-atlassian-bitbucket ls-repos --workspace-slug your-workspace

Permanent Installation

For regular use, install the package globally:

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

Configuration

For Claude Desktop

Edit your Claude configuration file:

For Scoped API Token:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
      }
    }
  }
}

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

Restart Claude Desktop after making changes.

Using Configuration File

You can also create a system-wide configuration file at ~/.mcp/configs.json:

For Scoped API Token:

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your_scoped_api_token",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

For Legacy App Password:

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

Usage Examples

Repository Exploration

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"

Pull Request Management

Ask your AI assistant:

• "Show me all open pull requests that need review"
• "Get details about pull request #42 including the code changes"
• "Create a pull request from feature-login to main branch"
• "Add a comment to PR #15 saying the tests passed"

Branch and Code Operations

Ask your AI assistant:

• "Compare my feature branch with the main branch"
• "Create a new branch called hotfix-login from the main branch"
• "List all branches in the user-service repository"
• "Show me the differences between commits abc123 and def456"

Troubleshooting

Authentication Issues

If you receive "Authentication failed" or "403 Forbidden":

1. Verify your credentials with a test command:

   npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces
   

2. For Scoped API Tokens:

   • Check that your token is active and has correct scopes
   • Ensure you're using your Atlassian email address

3. For App Passwords:

   • Verify the password has necessary permissions
   • Check that you're using your Bitbucket username

Workspace or Repository Issues

If you get "Workspace not found" or "Repository not found":

1. List available workspaces:

   npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces
   

2. Use the exact slug from your Bitbucket URL:

   • For https://bitbucket.org/myteam/my-repo
   • Workspace slug is myteam
   • Repository slug is my-repo

3. Set a default workspace to avoid specifying it every time:

   export BITBUCKET_DEFAULT_WORKSPACE="your-main-workspace-slug"
   

Claude Desktop Integration

If you're having issues with Claude Desktop:

1. Restart Claude Desktop after updating the config file
2. Check the status bar for the "🔗 bitbucket" indicator
3. Verify the config file location:
   • macOS: ~/.claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "bitbucket" '{"command":"npx","args":["-y","@aashari/mcp-server-atlassian-bitbucket"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect