Skip to content

INSTALLATION.md

Latest commit

 

History

History
436 lines (341 loc) · 12 KB

INSTALLATION.md

File metadata and controls

436 lines (341 loc) · 12 KB

Bitbucket MCP Server - Installation Guide

Complete guide for installing and configuring the Bitbucket MCP server with Claude Code.

Prerequisites

  • Python 3.11+ or pipx installed
  • Bitbucket account with API access
  • Claude Code CLI installed

Step 1: Install the Package

Option A: Using pipx (Recommended)

pipx install mcp-server-bitbucket

Option B: Using pip

pip install mcp-server-bitbucket

Option C: From Source

git clone https://github.com/JaviMaligno/mcp-server-bitbucket.git
cd mcp-server-bitbucket
uv sync

Step 2: Create Bitbucket API Token

Bitbucket uses Repository Access Tokens or Workspace Access Tokens for API authentication.

Creating a Repository Access Token

  1. Go to your repository in Bitbucket
  2. Navigate to Repository settings > Access tokens
  3. Click Create Repository Access Token
  4. Configure the token:
    • Name: Claude Code MCP (or any descriptive name)
    • Permissions - select the following:
      • Repository: Read, Write, Admin, Delete
      • Pull requests: Read, Write
      • Pipelines: Read, Write
      • Projects: Read (for list_projects, get_project)
      • Webhooks: Read, Write (for webhook management)
  5. Click Create
  6. Copy the token immediately - it won't be shown again!

Creating a Workspace Access Token (for multiple repos)

  1. Go to Workspace settings > Access tokens
  2. Click Create Workspace Access Token
  3. Configure the token:
    • Name: Claude Code MCP
    • Permissions:
      • Repositories: Read, Write, Admin, Delete
      • Pull requests: Read, Write
      • Pipelines: Read, Write
      • Projects: Read
      • Webhooks: Read, Write
  4. Click Create
  5. Copy the token immediately

Required Permissions Summary

Scope Permission Used for
Repositories Read list_repositories, get_repository, list_branches, get_branch, list_commits, get_commit, compare_commits, get_commit_statuses
Repositories Write create_repository, create_commit_status
Repositories Admin Repository settings, update_repository
Repositories Delete delete_repository
Pull requests Read list_pull_requests, get_pull_request, list_pr_comments, get_pr_diff
Pull requests Write create_pull_request, merge_pull_request, approve_pr, unapprove_pr, request_changes_pr, decline_pr, add_pr_comment
Pipelines Read list_pipelines, get_pipeline, get_pipeline_logs, list_environments, get_environment, list_deployment_history
Pipelines Write trigger_pipeline, stop_pipeline
Projects Read list_projects, get_project
Webhooks Read list_webhooks, get_webhook
Webhooks Write create_webhook, delete_webhook

Step 3: Configure Claude Code

Option A: Using CLI Command (Recommended)

Run this command, replacing the placeholders with your values:

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

With TOON format for ~30-40% token savings:

claude mcp add bitbucket -s user \
  -e OUTPUT_FORMAT=toon \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Example with real values:

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=simplekyc \
  -e BITBUCKET_EMAIL=javier@simplekyc.com \
  -e BITBUCKET_API_TOKEN=ATATT3xFfGF0KIXKm4Si... \
  -- mcp-server-bitbucket

Option B: Manual Configuration

Edit ~/.claude.json and add to the mcpServers section:

{
  "mcpServers": {
    "bitbucket": {
      "type": "stdio",
      "command": "mcp-server-bitbucket",
      "args": [],
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "your-email@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

Option C: Project-level Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "bitbucket": {
      "command": "mcp-server-bitbucket",
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "your-email@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

Warning: Don't commit .mcp.json with credentials to version control! Add it to .gitignore.

Step 4: Verify Installation

# Check MCP server is configured
claude mcp list

# Should show:
# bitbucket: ✓ Connected

Start a Claude Code session and test:

> List my Bitbucket repositories

Available Tools (58 total)

Repositories

Tool Description
list_repositories List and search repositories
get_repository Get repository details
create_repository Create a new repository
delete_repository Delete a repository
update_repository Update repo settings

Branches & Commits

Tool Description
list_branches List branches in a repo
get_branch Get branch details
list_commits List commits
get_commit Get commit details
compare_commits Compare two commits/branches

Tags

Tool Description
list_tags List tags in a repo
create_tag Create a new tag
delete_tag Delete a tag

Branch Restrictions

Tool Description
list_branch_restrictions List branch protection rules
create_branch_restriction Create protection rule
delete_branch_restriction Delete protection rule

Source (File Browsing)

Tool Description
get_file_content Read file contents
list_directory List directory contents

Commit Statuses

Tool Description
get_commit_statuses Get CI/CD statuses for a commit
create_commit_status Report build status

Pull Requests

Tool Description
list_pull_requests List PRs
get_pull_request Get PR details
create_pull_request Create a new PR
merge_pull_request Merge a PR
approve_pr Approve a PR
unapprove_pr Remove approval
request_changes_pr Request changes
decline_pr Decline a PR
list_pr_comments List PR comments
add_pr_comment Add a comment
get_pr_diff Get PR diff

Pipelines

Tool Description
list_pipelines List pipeline runs
get_pipeline Get pipeline status
get_pipeline_logs View pipeline logs
trigger_pipeline Trigger a pipeline
stop_pipeline Stop a pipeline

Pipeline Variables

Tool Description
list_pipeline_variables List pipeline variables
get_pipeline_variable Get variable details
create_pipeline_variable Create a variable
update_pipeline_variable Update variable value
delete_pipeline_variable Delete a variable

Deployments

Tool Description
list_environments List environments
get_environment Get environment details
list_deployment_history Get deployment history

Webhooks

Tool Description
list_webhooks List webhooks
create_webhook Create a webhook
get_webhook Get webhook details
delete_webhook Delete a webhook

Repository Permissions

Tool Description
list_user_permissions List user permissions
get_user_permission Get user's permission
update_user_permission Add/update user permission
delete_user_permission Remove user permission
list_group_permissions List group permissions
get_group_permission Get group's permission
update_group_permission Add/update group permission
delete_group_permission Remove group permission

Projects

Tool Description
list_projects List projects
get_project Get project details

Example Usage

Once configured, you can ask Claude to:

Repositories & Commits:

  • "List all repositories in my workspace"
  • "Search for repositories with 'api' in the name"
  • "Show me the last 10 commits on main"
  • "Compare develop branch with main"

Pull Requests & Code Review:

  • "Show me open pull requests in my-repo"
  • "Create a PR from feature-branch to main"
  • "Approve PR #42"
  • "Add a comment to PR #15"
  • "Show me the diff for PR #42"
  • "Merge PR #42 using squash strategy"

Pipelines & CI/CD:

  • "Trigger a pipeline on develop"
  • "What's the status of the latest pipeline?"
  • "Get build status for commit abc123"

Deployments:

  • "List deployment environments"
  • "Show deployment history for production"

Webhooks:

  • "List webhooks for my-repo"
  • "Create a webhook for push events"

Tags:

  • "List all tags in my-repo"
  • "Create a tag v1.0.0 on main"
  • "Delete the old-release tag"

Branch Protection:

  • "List branch restrictions for my-repo"
  • "Require 2 approvals to merge to main"

Source Browsing:

  • "Show me the contents of src/main.py"
  • "List files in the root directory"

Repository Permissions:

  • "List user permissions for my-repo"
  • "Give write access to user@example.com"
  • "List group permissions"

Repository Search

The list_repositories tool supports flexible searching:

Parameter Description Example
search Simple fuzzy name search search="api" finds repos with "api" in name
query Advanced Bitbucket query syntax query='name ~ "test" AND is_private = true'
project_key Filter by project project_key="MYPROJECT"

Query syntax: name ~ "term", description ~ "term", is_private = true/false, combined with AND/OR

Quick Reference: CLI Command

Copy and customize this command:

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=<workspace> \
  -e BITBUCKET_EMAIL=<email> \
  -e BITBUCKET_API_TOKEN=<token> \
  -- mcp-server-bitbucket

Where:

  • <workspace> - Your Bitbucket workspace slug (e.g., simplekyc)
  • <email> - Your Bitbucket account email
  • <token> - The API token you created in Step 2

Output Format Options

Variable Values Description
OUTPUT_FORMAT json (default), toon Response format. TOON saves ~30-40% tokens

Add -e OUTPUT_FORMAT=toon for token-optimized responses.

Troubleshooting

401 Unauthorized Error

  • Verify your API token is correct and hasn't expired
  • Check that the token has the required permissions
  • Ensure BITBUCKET_EMAIL matches your Bitbucket account email
  • For workspace tokens, ensure the workspace slug is correct

403 Forbidden Error

  • The token is missing required permissions
  • Go back to Bitbucket and add the missing permission scopes

MCP Server Not Connecting

# Check server status
claude mcp get bitbucket

# Verify pipx installation
which mcp-server-bitbucket

# Test server directly
mcp-server-bitbucket
# Should output nothing (waiting for MCP protocol messages)
# Press Ctrl+C to exit

Configuration Priority

Claude Code loads MCP configs in this order (later overrides earlier):

  1. User config: ~/.claude.json
  2. Project config: .mcp.json in project root

If you have both, the project config takes precedence. Remove project .mcp.json if you want to use user config.

Updating

# Update to latest version
pipx upgrade mcp-server-bitbucket

# Or reinstall for clean update
pipx uninstall mcp-server-bitbucket && pipx install mcp-server-bitbucket

Uninstalling

# Remove from Claude Code
claude mcp remove bitbucket -s user

# Uninstall package
pipx uninstall mcp-server-bitbucket

Support