Bitbucket Server MCP

MCP (Model Context Protocol) server for Bitbucket Server Pull Request management. This server provides tools and resources to interact with the Bitbucket Server API through the MCP protocol.

✨ New Features

🔍 Advanced Search: Search code and files across repositories with project/repository filtering using the search tool
📄 File Operations: Read file contents and browse repository directories with get_file_content and browse_repository
💬 Comment Management: Extract and filter PR comments with get_comments tool
🔍 Project Discovery: List all accessible Bitbucket projects with list_projects
📁 Repository Browsing: Explore repositories across projects with list_repositories
🔧 Flexible Project Support: Make the default project optional - specify per command or use BITBUCKET_DEFAULT_PROJECT
📖 Enhanced Documentation: Improved README with usage examples and better configuration guidance

Requirements

Node.js >= 16

Installation

Installing via Smithery

To install Bitbucket Server for Claude Desktop automatically via Smithery:

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

Manual Installation

npm install

Build

npm run build

Features

The server provides the following tools for comprehensive Bitbucket Server integration:

`list_projects`

Discover and explore Bitbucket projects: Lists all accessible projects with their details. Essential for project discovery and finding the correct project keys to use in other operations.

Use cases:

Find available projects when you don't know the exact project key
Explore project structure and permissions
Discover new projects you have access to

Parameters:

limit: Number of projects to return (default: 25, max: 1000)
start: Start index for pagination (default: 0)

`list_repositories`

Browse and discover repositories: Explore repositories within specific projects or across all accessible projects. Returns comprehensive repository information including clone URLs and metadata.

Use cases:

Find repository slugs for other operations
Explore codebase structure across projects
Discover repositories you have access to
Browse a specific project's repositories

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
limit: Number of repositories to return (default: 25, max: 1000)
start: Start index for pagination (default: 0)

`create_pull_request`

Propose code changes for review: Creates a new pull request to submit code changes, request reviews, or merge feature branches. Automatically handles branch references and reviewer assignments.

Use cases:

Submit feature development for review
Propose bug fixes
Request code integration from feature branches
Collaborate on code changes

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
title (required): Clear, descriptive PR title
description: Detailed description with context (supports Markdown)
sourceBranch (required): Source branch containing changes
targetBranch (required): Target branch for merging
reviewers: Array of reviewer usernames

`get_pull_request`

Comprehensive PR information: Retrieves detailed pull request information including status, reviewers, commits, and all metadata. Essential for understanding PR state before taking actions.

Use cases:

Check PR approval status
Review PR details and progress
Understand changes before merging
Monitor PR status

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID

`merge_pull_request`

Integrate approved changes: Merges an approved pull request into the target branch. Supports different merge strategies based on your workflow preferences.

Use cases:

Complete the code review process
Integrate approved features
Apply bug fixes to main branches
Release code changes

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID
message: Custom merge commit message
strategy: Merge strategy:
- merge-commit (default): Creates merge commit preserving history
- squash: Combines all commits into one
- fast-forward: Moves branch pointer without merge commit

`decline_pull_request`

Reject unsuitable changes: Declines a pull request that should not be merged, providing feedback to the author.

Use cases:

Reject changes that don't meet standards
Close PRs that conflict with project direction
Request significant rework
Prevent unwanted code integration

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID
message: Reason for declining (helpful for author feedback)

`add_comment`

Participate in code review: Adds comments to pull requests for review feedback, discussions, and collaboration. Supports threaded conversations.

Use cases:

Provide code review feedback
Ask questions about specific changes
Suggest improvements
Participate in technical discussions
Document review decisions

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID
text (required): Comment content (supports Markdown)
parentId: Parent comment ID for threaded replies

`get_diff`

Analyze code changes: Retrieves the code differences showing exactly what was added, removed, or modified in the pull request.

Use cases:

Review specific code changes
Understand scope of modifications
Analyze impact before merging
Inspect implementation details
Code quality assessment

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID
contextLines: Context lines around changes (default: 10)

`get_reviews`

Track review progress: Fetches review history, approval status, and reviewer feedback to understand the review state.

Use cases:

Check if PR is ready for merging
See who has reviewed the changes
Understand review feedback
Monitor approval requirements
Track review progress

`get_activities`

Retrieve pull request activities: Gets the complete activity timeline for a pull request including comments, reviews, commits, and other events.

Use cases:

Read comment discussions and feedback
Review the complete PR timeline
Track commits added/removed from PR
See approval and review history
Understand the full PR lifecycle

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID

`get_comments`

Extract PR comments only: Filters pull request activities to return only the comments, making it easier to focus on discussion content without reviews or other activities.

Use cases:

Read PR discussion threads
Extract feedback and questions
Focus on comment content without noise
Analyze conversation flow

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
prId (required): Pull request ID

`search`

Advanced code and file search: Search across repositories using the Bitbucket search API with support for project/repository filtering and query optimization. Searches both file contents and filenames. Note: Search only works on the default branch of repositories.

Use cases:

Find specific code patterns across projects
Locate files by name or content
Search within specific projects or repositories
Filter by file extensions

Parameters:

query (required): Search query string
project: Bitbucket project key to limit search scope
repository: Repository slug for repository-specific search
type: Query optimization - "file" (wraps query in quotes for exact filename matching) or "code" (default search behavior)
limit: Number of results to return (default: 25, max: 100)
start: Start index for pagination (default: 0)

Query syntax examples:

"README.md" - Find exact filename
config ext:yml - Find config in YAML files
function project:MYPROJECT - Search for "function" in specific project
bug fix repo:PROJ/my-repo - Search in specific repository

`get_file_content`

Read file contents with pagination: Retrieve the content of specific files from repositories with support for large files through pagination.

Use cases:

Read source code files
View configuration files
Extract documentation content
Inspect specific file versions

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
filePath (required): Path to the file in the repository
branch: Branch or commit hash (optional, defaults to main/master)
limit: Maximum lines per request (default: 100, max: 1000)
start: Starting line number for pagination (default: 0)

`browse_repository`

Explore repository structure: Browse files and directories in repositories to understand project organization and locate specific files.

Use cases:

Explore repository structure
Navigate directory trees
Find files and folders
Understand project organization

Parameters:

project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
repository (required): Repository slug
path: Directory path to browse (optional, defaults to root)
branch: Branch or commit hash (optional, defaults to main/master)
limit: Maximum items to return (default: 50)

Usage Examples

Listing Projects and Repositories

# List all accessible projects
list_projects

# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
list_repositories

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

# List projects with pagination
list_projects --limit 10 --start 0

Search and File Operations

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

# Search for specific 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"

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

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

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

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

Working with Pull Requests

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

# Create a pull request with specific project
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"

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

# Get only comments from a PR (no reviews/commits)
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123

# Get full PR activity timeline
get_activities --repository "my-repo" --prId 123

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

Dependencies

@modelcontextprotocol/sdk - SDK for MCP protocol implementation
axios - HTTP client for API requests
winston - Logging framework

Configuration

The server requires configuration in the VSCode MCP settings file. Here's a sample configuration:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        // Authentication (choose one):
        // Option 1: Personal Access Token
        "BITBUCKET_TOKEN": "your-access-token",
        // Option 2: Username/Password
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        // Optional: Default project
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}

Environment Variables

BITBUCKET_URL (required): Base URL of your Bitbucket Server instance
Authentication (one of the following is required):
- BITBUCKET_TOKEN: Personal access token
- BITBUCKET_USERNAME and BITBUCKET_PASSWORD: Basic authentication credentials
BITBUCKET_DEFAULT_PROJECT (optional): Default project key to use when not specified in tool calls
BITBUCKET_READ_ONLY (optional): Set to true to enable read-only mode

Note: With the new optional project support, you can now:

Set BITBUCKET_DEFAULT_PROJECT to work with a specific project by default
Use list_projects to discover available projects
Use list_repositories to browse repositories across projects
Override the default project by specifying the project parameter in any tool call

Read-Only Mode

The server supports a read-only mode for deployments where you want to prevent any modifications to your Bitbucket repositories. When enabled, only safe, non-modifying operations are available.

To enable read-only mode: Set the environment variable BITBUCKET_READ_ONLY=true

Available tools in read-only mode:

list_projects - Browse and list projects
list_repositories - Browse and list repositories
get_pull_request - View pull request details
get_diff - View code changes and diffs
get_reviews - View review history and status
get_activities - View pull request timeline
get_comments - View pull request comments
search - Search code and files across repositories
get_file_content - Read file contents
browse_repository - Browse repository structure

Disabled tools in read-only mode:

create_pull_request - Creating new pull requests
merge_pull_request - Merging pull requests
decline_pull_request - Declining pull requests
add_comment - Adding comments to pull requests

Behavior:

When BITBUCKET_READ_ONLY is not set or set to any value other than true, all tools function normally (backward compatible)
When BITBUCKET_READ_ONLY=true, write operations are filtered out and will return an error if called
This is perfect for production deployments, CI/CD integration, or any scenario where you need safe, read-only Bitbucket access

Logging

The server logs all operations to bitbucket.log using Winston for debugging and monitoring purposes.

Bitbucket Server MCP

README Documentation

Bitbucket Server MCP

✨ New Features

Requirements

Installation

Installing via Smithery

Manual Installation

Build

Features

`list_projects`

`list_repositories`

`create_pull_request`

`get_pull_request`

`merge_pull_request`

`decline_pull_request`

`add_comment`

`get_diff`

`get_reviews`

`get_activities`

`get_comments`

`search`

`get_file_content`

`browse_repository`

Usage Examples

Listing Projects and Repositories

Search and File Operations

Working with Pull Requests

Dependencies

Configuration

Environment Variables

Read-Only Mode

Logging

Quick Install

Quick Actions

Key Features