Bitbucket MCP server

This MCP server for Bitbucket Server allows you to interact with your Bitbucket repositories and pull requests using the Model Context Protocol. It provides tools for managing pull requests, searching code, browsing repositories, and accessing file content through a standardized interface.

Installation

Prerequisites

• Node.js 16 or higher

Installing via Smithery

The easiest way to install the Bitbucket Server MCP for Claude Desktop is through Smithery:

npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude

Manual Installation

To install manually:

npm install
npm run build

Configuration

The server requires configuration in your VSCode MCP settings file:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        
        // Authentication (choose one option):
        "BITBUCKET_TOKEN": "your-access-token",
        // OR
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        
        // Optional settings
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}

Environment Variables

• Required:

  • BITBUCKET_URL: Base URL of your Bitbucket Server instance
  • Authentication (one of these options):
    • BITBUCKET_TOKEN: Personal access token
    • BITBUCKET_USERNAME and BITBUCKET_PASSWORD: Basic authentication credentials

• Optional:

  • BITBUCKET_DEFAULT_PROJECT: Default project key to use when not specified
  • BITBUCKET_DIFF_MAX_LINES_PER_FILE: Maximum lines to show per file in diffs
  • BITBUCKET_READ_ONLY: Set to true to enable read-only mode

Read-Only Mode

Set BITBUCKET_READ_ONLY=true to prevent any modifications to your Bitbucket repositories. This disables all write operations like creating PRs, merging, and adding comments.

Using the MCP Server

Exploring Projects and Repositories

# List all accessible projects
list_projects

# List repositories in the default project
list_repositories

# List repositories in a specific project
list_repositories --project "MYPROJECT"

# Browse repository structure
browse_repository --project "MYPROJECT" --repository "my-repo"

# Browse specific directory
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"

Searching and Accessing Files

# Search for README files across all projects
search --query "README" --type "file"

# Search for code patterns in a project
search --query "function getUserData" --type "code" --project "MYPROJECT"

# Search with file extension filter
search --query "config ext:yml" --project "MYPROJECT"

# Read file contents
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json"

# Read specific lines from a large file
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "CHANGELOG.md" --start 100 --limit 50

Working with Pull Requests

# Create a pull request
create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"

# Get pull request details
get_pull_request --repository "my-repo" --prId 123

# View code changes in a pull request
get_diff --repository "my-repo" --prId 123

# Get only comments from a PR
get_comments --repository "my-repo" --prId 123

# Add a comment to a pull request
add_comment --repository "my-repo" --prId 123 --text "This looks good! Just a few suggestions..."

# Merge a pull request with squash strategy
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: New functionality (#123)"

# Decline a pull request
decline_pull_request --repository "my-repo" --prId 123 --message "Needs significant revisions"

Available Tools

Project and Repository Discovery

• list_projects: List all accessible Bitbucket projects
• list_repositories: Browse repositories within projects

Pull Request Management

• create_pull_request: Create new pull requests
• get_pull_request: View pull request details
• merge_pull_request: Merge approved pull requests (supports different strategies)
• decline_pull_request: Reject pull requests
• add_comment: Add comments to pull requests
• get_diff: View code changes in pull requests
• get_reviews: View review status and history
• get_activities: View complete PR timeline
• get_comments: Extract only comments from a PR

Code and File Operations

• search: Search across repositories for code and files
• get_file_content: Read file contents with pagination
• browse_repository: Explore repository structure

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":"node","args":["/path/to/bitbucket-server/build/index.js"],"env":{"BITBUCKET_URL":"https://your-bitbucket-server.com","BITBUCKET_TOKEN":"your-access-token","BITBUCKET_DEFAULT_PROJECT":"your-default-project"}}'

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": "node",
            "args": [
                "/path/to/bitbucket-server/build/index.js"
            ],
            "env": {
                "BITBUCKET_URL": "https://your-bitbucket-server.com",
                "BITBUCKET_TOKEN": "your-access-token",
                "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
            }
        }
    }
}

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": "node",
            "args": [
                "/path/to/bitbucket-server/build/index.js"
            ],
            "env": {
                "BITBUCKET_URL": "https://your-bitbucket-server.com",
                "BITBUCKET_TOKEN": "your-access-token",
                "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect