The Bitbucket MCP Server provides comprehensive tools for interacting with Bitbucket API (both Cloud and Server), enabling efficient repository management through:
- Pull Request Management: Create, retrieve, update, merge, and list pull requests with filtering and pagination options.
- Branch Operations: List, delete, and get detailed information about branches, including associated pull requests and commits.
- Code Review: Approve/unapprove pull requests, request/remove changes, add comments (inline, general, and replies), and view diffs.
- File and Directory Access: List directory contents and retrieve file content with smart truncation for large files.
- Collaboration Features: Add comments with code suggestions, configure merge strategies (merge-commit, squash, fast-forward), and customize commit messages.
These capabilities enable efficient workflow management for development teams using Bitbucket repositories.
Provides tools for interacting with the Bitbucket API, supporting both Bitbucket Cloud and Bitbucket Server. Enables management of pull requests (creating, updating, listing, approving, commenting), handling code reviews, working with branches, and viewing diffs.
Bitbucket MCP Server
An MCP (Model Context Protocol) server that provides tools for interacting with the Bitbucket API, supporting both Bitbucket Cloud and Bitbucket Server.
Features
Currently Implemented Tools
Core PR Lifecycle Tools
get_pull_request
- Retrieve detailed information about a pull requestlist_pull_requests
- List pull requests with filters (state, author, pagination)create_pull_request
- Create new pull requestsupdate_pull_request
- Update PR details (title, description, reviewers, destination branch)add_comment
- Add comments to pull requests (supports replies)merge_pull_request
- Merge pull requests with various strategieslist_pr_commits
- List all commits that are part of a pull requestdelete_branch
- Delete branches after merge
Branch Management Tools
list_branches
- List branches with filtering and paginationdelete_branch
- Delete branches (with protection checks)get_branch
- Get detailed branch information including associated PRslist_branch_commits
- List commits in a branch with advanced filtering
File and Directory Tools
list_directory_content
- List files and directories in a repository pathget_file_content
- Get file content with smart truncation for large files
Code Review Tools
get_pull_request_diff
- Get the diff/changes for a pull requestapprove_pull_request
- Approve a pull requestunapprove_pull_request
- Remove approval from a pull requestrequest_changes
- Request changes on a pull requestremove_requested_changes
- Remove change request from a pull request
Installation
Using npx (Recommended)
The easiest way to use this MCP server is directly with npx:
For Bitbucket Server:
From Source
- Clone or download this repository
- Install dependencies:
- Build the TypeScript code:
Authentication Setup
This server uses Bitbucket App Passwords for authentication.
Creating an App Password
- Log in to your Bitbucket account
- Navigate to: https://bitbucket.org/account/settings/app-passwords/
- Click "Create app password"
- Give it a descriptive label (e.g., "MCP Server")
- Select the following permissions:
- Account: Read
- Repositories: Read, Write
- Pull requests: Read, Write
- Click "Create"
- Important: Copy the generated password immediately (you won't be able to see it again!)
Running the Setup Script
This will guide you through the authentication setup process.
Configuration
Add the server to your MCP settings file (usually located at ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
):
Replace:
/absolute/path/to/bitbucket-mcp-server
with the actual path to this directoryyour-username
with your Bitbucket username (not email)your-app-password
with the app password you created
For Bitbucket Server, use:
Important for Bitbucket Server users:
- Use your full email address as the username (e.g., "john.doe@company.com")
- This is required for approval/review actions to work correctly
Usage
Once configured, you can use the available tools:
Get Pull Request
Returns detailed information about the pull request including:
- Title and description
- Author and reviewers
- Source and destination branches
- Approval status
- Links to web UI and diff
- Merge commit details (when PR is merged):
merge_commit_hash
: The hash of the merge commitmerged_by
: Who performed the mergemerged_at
: When the merge occurredmerge_commit_message
: The merge commit message
- Active comments with nested replies (unresolved comments that need attention):
active_comments
: Array of active comments (up to 20 most recent top-level comments)- Comment text and author
- Creation date
- Whether it's an inline comment (with file path and line number)
- Nested replies (for Bitbucket Server):
replies
: Array of reply comments with same structure- Replies can be nested multiple levels deep
- Parent reference (for Bitbucket Cloud):
parent_id
: ID of the parent comment for replies
active_comment_count
: Total count of unresolved comments (including nested replies)total_comment_count
: Total count of all comments (including resolved and replies)
- File changes:
file_changes
: Array of all files modified in the PR- File path
- Status (added, modified, removed, or renamed)
- Old path (for renamed files)
file_changes_summary
: Summary statistics- Total files changed
- And more...
List Pull Requests
Returns a paginated list of pull requests with:
- Array of pull requests with same details as get_pull_request
- Total count of matching PRs
- Pagination info (has_more, next_start)
Note on Author Filter:
- For Bitbucket Cloud: Use the username (e.g., "johndoe")
- For Bitbucket Server: Use the full email address (e.g., "john.doe@company.com")
Create Pull Request
Update Pull Request
Important Note on Reviewers:
- When updating a PR without specifying the
reviewers
parameter, existing reviewers and their approval status are preserved - When providing the
reviewers
parameter:- The reviewer list is replaced with the new list
- For reviewers that already exist on the PR, their approval status is preserved
- New reviewers are added without approval status
- This prevents accidentally removing reviewers when you only want to update the PR description or title
Add Comment
Add a comment to a pull request, either as a general comment or inline on specific code:
The suggestion feature formats comments using GitHub-style markdown suggestion blocks that Bitbucket can render. When adding a suggestion:
suggestion
is required and contains the replacement codefile_path
andline_number
are required when using suggestionssuggestion_end_line
is optional and used for multi-line suggestions (defaults toline_number
)- The comment will be formatted with a ````suggestion` markdown block that may be applicable in the Bitbucket UI
Using Code Snippets Instead of Line Numbers
The add_comment
tool now supports finding line numbers automatically using code snippets. This is especially useful when AI tools analyze diffs and may struggle with exact line numbers:
Code Snippet Parameters:
code_snippet
: The exact code line to find (alternative toline_number
)search_context
: Optional context to disambiguate multiple matchesbefore
: Array of lines that should appear before the targetafter
: Array of lines that should appear after the target
match_strategy
: How to handle multiple matches"strict"
(default): Fail with error showing all matches"best"
: Auto-select the highest confidence match
Error Response for Multiple Matches (strict mode):
This feature is particularly useful for:
- AI-powered code review tools that analyze diffs
- Scripts that automatically add comments based on code patterns
- Avoiding line number confusion in large diffs
Note on comment replies:
- Use
parent_comment_id
to reply to any comment (general or inline) - In
get_pull_request
responses:- Bitbucket Server shows replies nested in a
replies
array - Bitbucket Cloud shows a
parent_id
field for reply comments
- Bitbucket Server shows replies nested in a
- You can reply to replies, creating nested conversations
Note on inline comments:
file_path
: The path to the file as shown in the diffline_number
: The line number as shown in the diffline_type
:ADDED
- For newly added lines (green in diff)REMOVED
- For deleted lines (red in diff)CONTEXT
- For unchanged context lines
Add Comment - Complete Usage Guide
The add_comment
tool supports multiple scenarios. Here's when and how to use each approach:
1. General PR Comments (No file/line)
- Use when: Making overall feedback about the PR
- Required params:
comment_text
only - Example: "LGTM!", "Please update the documentation"
2. Reply to Existing Comments
- Use when: Continuing a conversation thread
- Required params:
comment_text
,parent_comment_id
- Works for both general and inline comment replies
3. Inline Comments with Line Number
- Use when: You know the exact line number from the diff
- Required params:
comment_text
,file_path
,line_number
- Optional:
line_type
(defaults to CONTEXT)
4. Inline Comments with Code Snippet
- Use when: You have the code but not the line number (common for AI tools)
- Required params:
comment_text
,file_path
,code_snippet
- The tool will automatically find the line number
- Add
search_context
if the code appears multiple times - Use
match_strategy: "best"
to auto-select when multiple matches exist
5. Code Suggestions
- Use when: Proposing specific code changes
- Required params:
comment_text
,file_path
,line_number
,suggestion
- For multi-line: also add
suggestion_end_line
- Creates applicable suggestion blocks in Bitbucket UI
Decision Flow for AI/Automated Tools:
Common Pitfalls to Avoid:
- Don't use both
line_number
andcode_snippet
- pick one - Suggestions always need
file_path
andline_number
- Code snippets must match exactly (including whitespace)
- REMOVED lines reference the source file, ADDED/CONTEXT reference the destination
Merge Pull Request
List Branches
Returns a paginated list of branches with:
- Branch name and ID
- Latest commit hash
- Default branch indicator
- Pagination info
Delete Branch
Note: Branch deletion requires appropriate permissions. The branch will be permanently deleted.
Get Branch
Returns comprehensive branch information including:
- Branch details:
- Name and ID
- Latest commit (hash, message, author, date)
- Default branch indicator
- Open pull requests from this branch:
- PR title and ID
- Destination branch
- Author and reviewers
- Approval status (approved by, changes requested by, pending)
- PR URL
- Merged pull requests (if
include_merged_prs
is true):- PR title and ID
- Merge date and who merged it
- Statistics:
- Total open PRs count
- Total merged PRs count
- Days since last commit
This tool is particularly useful for:
- Checking if a branch has open PRs before deletion
- Getting an overview of branch activity
- Understanding PR review status
- Identifying stale branches
List Branch Commits
Get all commits in a specific branch with advanced filtering options:
Filter Parameters:
since
: ISO date string - only show commits after this dateuntil
: ISO date string - only show commits before this dateauthor
: Filter by author email/usernameinclude_merge_commits
: Boolean to include/exclude merge commits (default: true)search
: Search for text in commit messages
Returns detailed commit information:
This tool is particularly useful for:
- Reviewing commit history before releases
- Finding commits by specific authors
- Tracking changes within date ranges
- Searching for specific features or fixes
- Analyzing branch activity patterns
List PR Commits
Get all commits that are part of a pull request:
Returns commit information for the PR:
This tool is particularly useful for:
- Reviewing all changes in a PR before merging
- Understanding the development history of a PR
- Checking commit messages for quality
- Verifying authorship of changes
- Analyzing PR complexity by commit count
Get Pull Request Diff
Get the diff/changes for a pull request with optional filtering capabilities:
Filtering Options:
include_patterns
: Array of glob patterns to include (whitelist)exclude_patterns
: Array of glob patterns to exclude (blacklist)file_path
: Get diff for a specific file only- Patterns support standard glob syntax (e.g.,
*.js
,src/**/*.res
,!test/**
)
Response includes filtering metadata:
Approve Pull Request
Request Changes
List Directory Content
Returns directory listing with:
- Path and branch information
- Array of contents with:
- Name
- Type (file or directory)
- Size (for files)
- Full path
- Total items count
Get File Content
Smart Truncation Features:
- Automatically truncates large files (>50KB) to prevent token overload
- Default line counts based on file type:
- Config files (.yml, .json): 200 lines
- Documentation (.md, .txt): 300 lines
- Code files (.ts, .js, .py): 500 lines
- Log files: Last 100 lines
- Use
start_line: -50
to get last 50 lines (tail functionality) - Files larger than 1MB require explicit
full_content: true
or line parameters
Returns file content with:
- File path and branch
- File size and encoding
- Content (full or truncated based on parameters)
- Line information (if truncated):
- Total lines in file
- Range of returned lines
- Truncation indicator
- Last modified information (commit, author, date)
Example responses:
Development
npm run dev
- Watch mode for developmentnpm run build
- Build the TypeScript codenpm start
- Run the built server
Troubleshooting
- Authentication errors: Double-check your username and app password
- 404 errors: Verify the workspace, repository slug, and PR ID
- Permission errors: Ensure your app password has the required permissions
License
MIT
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
An MCP server that enables interaction with Bitbucket repositories through the Model Context Protocol, supporting both Bitbucket Cloud and Server with features for PR lifecycle management and code review.
Related MCP Servers
- -securityAlicense-qualityMCP Server simplifies the implementation of the Model Context Protocol by providing a user-friendly API to create custom tools and manage server workflows efficiently.Last updated -43TypeScriptMIT License
- AsecurityAlicenseAqualityFacilitates interaction with Bitbucket Server for pull request management using the MCP protocol, supporting operations such as creating, merging, commenting, and reviewing pull requests.Last updated -718JavaScriptApache 2.0
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Bitbucket repositories, pull requests, and other resources through Bitbucket Cloud and Server APIs.Last updated -3854JavaScriptMIT License
- -securityFlicense-qualityA comprehensive Model Context Protocol (MCP) server implementing the latest MCP specification with tools, resources, prompts, and enhanced sampling capabilities that features HackerNews and GitHub API integrations for AI-powered analysis.Last updated -319Python