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

🔍 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

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

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

# 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

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

Logging

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

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
.github/workflows		.github/workflows
src		src
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

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`

Usage Examples

Listing Projects and Repositories

Working with Pull Requests

Dependencies

Configuration

Environment Variables

Logging

About

Uh oh!

Releases

Packages

Uh oh!

Contributors 4

Languages

License

garc33/bitbucket-server-mcp-server

Folders and files

Latest commit

History

Repository files navigation

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

Usage Examples

Listing Projects and Repositories

Working with Pull Requests

Dependencies

Configuration

Environment Variables

Logging

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 4

Languages

`list_projects`

`list_repositories`

`create_pull_request`

`get_pull_request`

`merge_pull_request`

`decline_pull_request`

`add_comment`

`get_diff`

`get_reviews`

Packages