Nikita — Bitbucket MCP Server

A Model Context Protocol (MCP) server for interacting with Bitbucket Cloud and Bitbucket Server (Stash) APIs. Provides tools for managing repositories, pull requests, branches, commits, and more.

Features

• Dual support for Bitbucket Cloud and Bitbucket Server/Data Center
• 25 tools covering repos, PRs, branches, commits, diffs, and comments
• Automatic auth detection — Basic auth for Cloud, Bearer token for Server
• Structured error handling with retryable error classification

Prerequisites

• Node.js v18 or later

Installation

npm install

Configuration

The server reads credentials from environment variables:

| Variable | Required | Description | |---|---|---| | ATLASSIAN_USER_EMAIL | Yes | Your Bitbucket email | | ATLASSIAN_API_TOKEN | Yes | App password (Cloud) or personal access token (Server) | | ATLASSIAN_SITE_URL | No | API base URL. Defaults to https://api.bitbucket.org/2.0 for Cloud. Use your Server REST API URL (e.g. https://stash.example.com/rest/api/1.0) for Bitbucket Server. | | BITBUCKET_DEFAULT_DEST_BRANCH | No | Default destination branch for PRs (default: main) |

Alternatively, place a mcp.config.json, .mcp.config.json, or .bitbucket.mcp.json in your working directory:

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your-token",
      "ATLASSIAN_SITE_URL": "https://stash.example.com/rest/api/1.0"
    },
    "defaultDestinationBranch": "main"
  }
}

Usage with Windsurf

Add this to your Windsurf MCP configuration:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "[email protected]"
      ],
      "disabled": false,
      "env": {
        "ATLASSIAN_API_TOKEN": "<YOUR_TOKEN>",
        "ATLASSIAN_SITE_URL": "site",
        "ATLASSIAN_USER_EMAIL": "[email protected]"
      }
    }
  }
}

Available Tools

Repository

| Tool | Description | |---|---| | repo_info | Get repository details | | repos_list | List repositories in a workspace | | workspaces_list | List all accessible workspaces |

Pull Requests

| Tool | Description | |---|---| | pr_list | List pull requests (filter by state) | | pr_get | Get PR details | | pr_create | Create a pull request | | pr_update | Update PR title/description | | pr_diff | Get PR diff | | pr_changes | Get file changes in a PR | | pr_approve | Approve a PR | | pr_decline | Decline a PR | | pr_merge | Merge a PR (with strategy options) | | pr_comment_add | Add a comment to a PR | | pr_inline_comment_add | Add an inline comment at a specific file/line | | pr_comments_list | List all PR comments | | pr_reviewers_add | Add reviewers to a PR |

Branches

| Tool | Description | |---|---| | branches_list | List branches | | branch_create | Create a branch from a commit hash | | branch_compare | Compare two branches |

Commits

| Tool | Description | |---|---| | commits_list | List commits (optionally by branch/range) | | commit_get | Get commit details | | commit_diff | Get diff for a commit |

Other

| Tool | Description | |---|---| | file_content | Get file content at a specific commit | | connection_test | Test API connectivity |

Project Structure

PR/
├── package.json
├── README.md
└── src/
    ├── cli.js         # MCP server entry point (stdio transport)
    ├── bitbucket.js   # BitbucketClient — API wrapper
    ├── config.js      # Configuration loader
    └── git.js         # Git helpers (branch, remote, repo root)

License

ISC