Bitbucket
About
Integrates with Bitbucket's API to streamline pull request workflows, enabling efficient code reviews and automated PR management.
Details
- Author
- garc33
- Repository
- garc33/bitbucket-server-mcp-server
- GitHub stars
- 36
- Downloads
- 546
- License
- Apache License 2.0
- Categories
- Developer Tools, Other, Project Management, Infrastructure, Productivity, Design, Workplace, AI, Communication, Knowledge Base
Jump to
The server provides the following tools for comprehensive Bitbucket Server integration:
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
BitbucketCommand (node, npx, python, etc.)nodeArguments-
Argument 1
/path/to/bitbucket-server/build/index.js
Environment-
BITBUCKET_URL
https://your-bitbucket-server.com -
BITBUCKET_TOKEN
your-access-token -
BITBUCKET_PASSWORD
your-password -
BITBUCKET_USERNAME
your-username -
BITBUCKET_DEFAULT_PROJECT
your-default-project
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
-
Argument 1
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
To install Bitbucket Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude
npm install
list_projects
Discover and explore Bitbucket projects. Lists all accessible projects with their details. 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. Parameters: project (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. Parameters: project (optional), repository (required), title (required), description, sourceBranch (required), targetBranch (required), reviewers, sourceProject, sourceRepository, includeDefaultReviewers
update_pull_request
Safely update a pull request. Modify the title, description, or reviewers of an existing pull request. Parameters: project (optional), repository (required), prId (required), title, description, reviewers
get_pull_request
Retrieves detailed pull request information including status and metadata. Parameters: project (optional), repository (required), prId (required)
merge_pull_request
Merges an approved pull request into the target branch. Parameters: project (optional), repository (required), prId (required), message, strategy
decline_pull_request
Declines a pull request that should not be merged. Parameters: project (optional), repository (required), prId (required), message
add_comment
Adds comments to pull requests for review feedback. Parameters: project (optional), repository (required), prId (required), text (required), parentId, state
get_diff
Retrieves the code differences in the pull request. Parameters: project (optional), repository (required), prId (required), contextLines, maxLinesPerFile
get_reviews
Fetches review history and approval status for a pull request.
get_activities
Gets the complete activity timeline for a pull request. Parameters: project (optional), repository (required), prId (required)
get_comments
Filters pull request activities to return only the comments. Parameters: project (optional), repository (required), prId (required)
search
Search across repositories. Parameters: query (required), project, repository, type, limit, start
get_file_content
Retrieve the content of specific files from repositories. Parameters: project (optional), repository (required), filePath (required), branch, limit, start
browse_repository
Browse files and directories in repositories. Parameters: project (optional), repository (required), path, branch, limit
list_pull_requests
List pull requests in a repository with filtering by state, author, and direction. Parameters: project (optional), repository (required), state, author, direction, limit, start
list_branches
List branches in a repository with optional filtering. Parameters: project (optional), repository (required), filterText, limit, start
list_commits
List commits in a repository with optional branch and author filtering. Parameters: project (optional), repository (required), branch, author, limit, start
delete_branch
Delete a branch from a repository. Parameters: project (optional), repository (required), branch (required)
approve_pull_request
Approve a pull request as the current authenticated user. Parameters: project (optional), repository (required), prId (required)
unapprove_pull_request
Remove your approval from a pull request. Parameters: project (optional), repository (required), prId (required)
edit_comment
Modify the text of a comment on a pull request. Parameters: project (optional), repository (required), prId (required), commentId (required), text (required), version (required)
delete_comment
Remove a comment from a pull request. Parameters: project (optional), repository (required), prId (required), commentId (required), version (required)
publish_review
Publish all pending comments at once. Parameters: project (optional), repository (required), prId (required), commentText, participantStatus
get_code_insights
Fetch Code Insights reports for a pull request. Parameters: project (optional), repository (required), prId (required)
get_dashboard_pull_requests
List pull requests across all repositories for the authenticated user. Parameters: state, role, participantStatus, order, closedSince, limit, start
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"bitbucket": {
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your-access-token",
"BITBUCKET_PASSWORD": "your-password",
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_DEFAULT_PROJECT": "your-default-project"
},
"args": [
"/path/to/bitbucket-server/build/index.js"
],
"command": "node"
}
}
}
Linux
{
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your-access-token",
"BITBUCKET_PASSWORD": "your-password",
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_DEFAULT_PROJECT": "your-default-project"
},
"args": [
"/path/to/bitbucket-server/build/index.js"
],
"command": "node"
}
Macos
{
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your-access-token",
"BITBUCKET_PASSWORD": "your-password",
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_DEFAULT_PROJECT": "your-default-project"
},
"args": [
"/path/to/bitbucket-server/build/index.js"
],
"command": "node"
}
Windows
{
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your-access-token",
"BITBUCKET_PASSWORD": "your-password",
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_DEFAULT_PROJECT": "your-default-project"
},
"args": [
"/c",
"node",
"/path/to/bitbucket-server/build/index.js"
],
"command": "cmd"
}
Manage pull requests on Bitbucket Server.
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.
- π§ Custom HTTP Headers: Add custom headers to all requests viaBITBUCKET_CUSTOM_HEADERSenvironment variable (useful for Zero Trust tokens or proxies)
- π PR Discovery: List and filter pull requests by state, author, or direction usinglist_pull_requests(fixes #14)
- πΏ Branch Management: List branches with default branch detection usinglist_branches, delete merged branches withdelete_branch
- π Commit History: Browse commit history with branch and author filtering usinglist_commits
- β
PR Approval: Approve and unapprove pull requests withapprove_pull_requestandunapprove_pull_request
- π Advanced Search: Search code and files across repositories with project/repository filtering using thesearchtool
- π File Operations: Read file contents and browse repository directories withget_file_contentandbrowse_repository
- π¬ Comment Management: Extract and filter PR comments withget_commentstool
- π Project Discovery: List all accessible Bitbucket projects withlist_projects
- π Repository Browsing: Explore repositories across projects withlist_repositories
- π§ Flexible Project Support: Make the default project optional - specify per command or useBITBUCKET_DEFAULT_PROJECT
- π Enhanced Documentation: Improved README with usage examples and better configuration guidance
To install Bitbucket Server for Claude Desktop automatically viaSmithery:
npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude
The server provides the following tools for comprehensive Bitbucket Server integration:
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.
- Find available projects when you don't know the exact project key
- Explore project structure and permissions
- Discover new projects you have access to
- limit: Number of projects to return (default: 25, max: 1000)
- start: Start index for pagination (default: 0)
Browse and discover repositories: Explore repositories within specific projects or across all accessible projects. Returns comprehensive repository information including clone URLs and metadata.
- Find repository slugs for other operations
- Explore codebase structure across projects
- Discover repositories you have access to
- Browse a specific project's repositories
- 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)
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.
- Submit feature development for review
- Propose bug fixes
- Request code integration from feature branches
- Collaborate on code changes
- 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
- sourceProject: Project key of the source repository (for cross-repo PRs from forks)
- sourceRepository: Slug of the source repository (for cross-repo PRs from forks)
- includeDefaultReviewers: Automatically fetch and include default reviewers configured for the target branch (default: true)
Safely update a pull request: Modify the title, description, or reviewers of an existing pull request without losing any metadata. Uses a read-modify-write pattern to preserve all fields not explicitly changed.
- Fix PR title or description after creation
- Add or replace reviewers without losing existing ones
- Update PR metadata without affecting approval status
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID to update
- title: New title (if omitted, current title is preserved)
- description: New description (if omitted, current description is preserved)
- reviewers: New reviewer list as array of usernames (if omitted, current reviewers are preserved)
Comprehensive PR information: Retrieves detailed pull request information including status, reviewers, commits, and all metadata. Essential for understanding PR state before taking actions.
- Check PR approval status
- Review PR details and progress
- Understand changes before merging
- Monitor PR status
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID
Integrate approved changes: Merges an approved pull request into the target branch. Supports different merge strategies based on your workflow preferences.
- Complete the code review process
- Integrate approved features
- Apply bug fixes to main branches
- Release code changes
- 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
Reject unsuitable changes: Declines a pull request that should not be merged, providing feedback to the author.
- Reject changes that don't meet standards
- Close PRs that conflict with project direction
- Request significant rework
- Prevent unwanted code integration
- 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)
Participate in code review: Adds comments to pull requests for review feedback, discussions, and collaboration. Supports threaded conversations.
- Provide code review feedback
- Ask questions about specific changes
- Suggest improvements
- Participate in technical discussions
- Document review decisions
- 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
- state: Comment state:OPEN(default, published immediately) orPENDING(draft, visible only to you until review is published)
Analyze code changes: Retrieves the code differences showing exactly what was added, removed, or modified in the pull request. Supports per-file truncation to manage large diffs effectively.
- Review specific code changes
- Understand scope of modifications
- Analyze impact before merging
- Inspect implementation details
- Code quality assessment
- Handle large files without overwhelming output
- 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)
- maxLinesPerFile: Maximum lines to show per file (optional, uses BITBUCKET_DIFF_MAX_LINES_PER_FILE env var if not specified, set to 0 for no limit)
Large File Handling:When a file exceeds themaxLinesPerFilelimit, it shows:
- File headers and metadata (always preserved)
- First 60% of allowed lines from the beginning
- Truncation message with file statistics
- Last 40% of allowed lines from the end
- Clear indication of how to see the complete diff
Track review progress: Fetches review history, approval status, and reviewer feedback to understand the review state.
- Check if PR is ready for merging
- See who has reviewed the changes
- Understand review feedback
- Monitor approval requirements
- Track review progress
Retrieve pull request activities: Gets the complete activity timeline for a pull request including comments, reviews, commits, and other events.
- 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
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID
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.
- Read PR discussion threads
- Extract feedback and questions
- Focus on comment content without noise
- Analyze conversation flow
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID
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.
- Find specific code patterns across projects
- Locate files by name or content
- Search within specific projects or repositories
- Filter by file extensions
- 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)
- "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
Read file contents with pagination: Retrieve the content of specific files from repositories with support for large files through pagination.
- Read source code files
- View configuration files
- Extract documentation content
- Inspect specific file versions
- 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)
Explore repository structure: Browse files and directories in repositories to understand project organization and locate specific files.
- Explore repository structure
- Navigate directory trees
- Find files and folders
- Understand project organization
- 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)
Discover and filter pull requests: List pull requests in a repository with filtering by state, author, and direction. Returns PR metadata including title, author, branches, reviewers, and status.
- Find open PRs in a repository
- List your own pull requests
- See PRs awaiting review
- Get an overview of merged or declined PRs
- Monitor PR activity in a project
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- state: Filter by PR state βOPEN(default),MERGED,DECLINED, orALL
- author: Filter by author username (exact match)
- direction:INCOMING(PRs targeting this repo, default) orOUTGOING(PRs from this repo)
- limit: Number of PRs to return (default: 25, max: 1000)
- start: Start index for pagination (default: 0)
Explore repository branches: List branches in a repository with optional filtering. Identifies the default branch and shows latest commit information for each branch.
- Find branch names for PR creation or checkout
- Verify branch existence before operations
- Identify the default branch
- Search for branches by name
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- filterText: Filter branches by name (case-insensitive partial match)
- limit: Number of branches to return (default: 25, max: 1000)
- start: Start index for pagination (default: 0)
Browse commit history: List commits in a repository with optional branch and author filtering. Use this to review changes, track contributions, or understand the evolution of a branch.
- Review recent changes on a branch
- Find commits by a specific author
- Track commit history before merging
- Understand branch evolution
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- branch: Branch name to list commits from (defaults to the repository's default branch)
- author: Filter by author name or email (case-insensitive partial match, applied client-side)
- limit: Number of commits to return (default: 25, max: 1000)
- start: Start index for pagination (default: 0)
Clean up merged branches: Delete a branch from a repository. Includes a safety check to prevent deletion of the default branch.
- Clean up feature branches after PR merge
- Remove stale or abandoned branches
- Repository maintenance and hygiene
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- branch(required): Branch name to delete
Approve code changes: Approve a pull request as the current authenticated user. Records your approval on the PR, signaling that changes are ready to merge.
- Approve reviewed pull requests
- Signal readiness for merge
- Complete code review workflow
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID to approve
Retract approval: Remove your approval from a pull request. Use this when you need to retract a previous approval after discovering issues or when the PR has changed.
- Retract approval after discovering issues
- Remove approval when PR scope changes
- Correct accidental approvals
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID to remove approval from
Edit an existing comment: Modify the text of a comment on a pull request. Works with both published and pending (draft) comments. Requires the comment version for optimistic locking.
- Fix typos or formatting in review comments
- Update information in an existing comment
- Reformat comments (e.g., to Conventional Comments style)
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID the comment belongs to
- commentId(required): ID of the comment to edit
- text(required): New text content (supports Markdown)
- version(required): Current version of the comment for optimistic locking (fromget_commentsoradd_commentresponse)
Delete a comment: Remove a comment from a pull request. Requires the comment version for optimistic locking.
- Remove incorrectly posted comments
- Clean up draft comments that are no longer needed
- project: Bitbucket project key (optional, uses BITBUCKET_DEFAULT_PROJECT if not provided)
- repository(required): Repository slug
- prId(required): Pull request ID the comment belongs to
- commentId(required): ID of the comment to delete
- version(required): Current version of the comment for optimistic locking
Publish a batch review: Publish all pending (draft) comments at once, optionally setting your review status and adding an overview comment. This is the equivalent of clicking "Finish review" in the Bitbucket UI.
- Publish all draft review comments in a single action
- Approve a PR along with review comments
- Request changes with a "needs work" status and feedback
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.





