# 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)

```bash
pipx install mcp-server-bitbucket
```

### Option B: Using pip

```bash
pip install mcp-server-bitbucket
```

### Option C: From Source

```bash
git clone https://github.com/simplekyc/bitbucket-mcp.git
cd bitbucket-mcp
poetry install
```

## 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:

```bash
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:**

```bash
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:**

```bash
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:

```json
{
  "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:

```json
{
  "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

```bash
# 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 (53 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 |

### 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:

```bash
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

```bash
# 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

```bash
# 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

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

# Uninstall package
pipx uninstall mcp-server-bitbucket
```

## Support

- Bitbucket Issues: https://bitbucket.org/simplekyc/bitbucket-mcp/issues
- PyPI: https://pypi.org/project/mcp-server-bitbucket/
