# Bitbucket MCP Server

An MCP server that connects Claude Desktop and Claude Code to Bitbucket Cloud, enabling AI-assisted bug triage, impact analysis from live repository data.

## Tools

| Tool | Description |
|---|---|
| `search_by_jira_id` | Find PRs (by title/branch) and commits (by message) linked to a Jira issue key. Searches one repo or all repos in the workspace. |
| `search_by_pr_title` | Search PRs by keyword — returns details, description, comments, and changed files in one response |
| `get_changed_files` | List modified files with line add/remove counts for a PR number or commit hash |
| `get_diff` | Return the full unified diff for a PR or commit, truncated at a line boundary if over 50,000 characters |
| `get_file_content` | Return the full content of a file at a given branch or commit ref |
| `get_commit_history_for_file` | Show commit history for a file — frequency, authors, and dates |
| `get_related_prs` | Find other PRs that touched the same files as a given PR or commit |
| `list_repos` | List all repositories in the configured workspace |

## Authentication

Bitbucket Cloud uses Basic Auth with a **Bitbucket API Token** 

1. Go to Bitbucket -> Account Settings -> Security -> API Tokens
2. Create a Token with Scope

## Quick setup (Windows)

Run the setup script — it installs dependencies, builds, prompts for credentials, and registers the server in both Claude Desktop and Claude Code:

```powershell
powershell -ExecutionPolicy Bypass -File setup.ps1
```

Credentials are written to `.env.local` (git-ignored). The MCP config entry stays secret-free.

## Manual setup

### 1. Install and build

```bash
npm install
npm run build
```

### 2. Create `.env.local`

```
BITBUCKET_WORKSPACE=https://bitbucket.org/your-workspace/workspace/overview/
BITBUCKET_EMAIL=you@example.com
BITBUCKET_API_TOKEN=your_app_password_here
```

### 3. Register in Claude Desktop

Open `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) and add:

```json
{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["C:/path/to/bitbucket-mcp-server/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop to load the tools.

### 4. Register in Claude Code

```bash
claude mcp add bitbucket node "C:/path/to/bitbucket-mcp-server/dist/index.js" --scope user
```

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `BITBUCKET_WORKSPACE` | Yes | Full workspace URL or slug (e.g. `my-workspace`) |
| `BITBUCKET_EMAIL` | Yes | Your Atlassian account email |
| `BITBUCKET_API_TOKEN` | Yes | Bitbucket App Password (from account → App passwords) |

## Example prompts

```
"Show me all PRs and commits related to PROJ-123"
"Search PRs mentioning login timeout in repo my-service"
"What files were changed in PR 42 in repo my-service?"
"Get the diff for commit a1b2c3d4 in repo my-service"
"Show me the content of src/auth.ts on the main branch"
"Who has been changing src/payment/processor.ts and how often?"
"Find other PRs that touched the same files as PR 42"
"List all repos in the workspace"
```