@nexus2520/bitbucket-mcp-server
Advanced tools
MCP server for Bitbucket API integration - supports both Cloud and Server
An MCP (Model Context Protocol) server that provides tools for interacting with the Bitbucket API, supporting both Bitbucket Cloud and Bitbucket Server.
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 strategiesdelete_branch - Delete branches after mergelist_branches - List branches with filtering and paginationdelete_branch - Delete branches (with protection checks)get_branch - Get detailed branch information including associated PRslist_directory_content - List files and directories in a repository pathget_file_content - Get file content with smart truncation for large filesget_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 requestThe easiest way to use this MCP server is directly with npx:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@nexus2520/bitbucket-mcp-server"
],
"env": {
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_APP_PASSWORD": "your-app-password"
}
}
}
}
For Bitbucket Server:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@nexus2520/bitbucket-mcp-server"
],
"env": {
"BITBUCKET_USERNAME": "your.email@company.com",
"BITBUCKET_TOKEN": "your-http-access-token",
"BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
}
}
}
}
npm install
npm run build
This server uses Bitbucket App Passwords for authentication.
node scripts/setup-auth.js
This will guide you through the authentication setup process.
Add the server to your MCP settings file (usually located at ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):
{
"mcpServers": {
"bitbucket": {
"command": "node",
"args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
"env": {
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_APP_PASSWORD": "your-app-password"
}
}
}
}
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 createdFor Bitbucket Server, use:
{
"mcpServers": {
"bitbucket": {
"command": "node",
"args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
"env": {
"BITBUCKET_USERNAME": "your.email@company.com",
"BITBUCKET_TOKEN": "your-http-access-token",
"BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
}
}
}
}
Important for Bitbucket Server users:
Once configured, you can use the available tools:
{
"tool": "get_pull_request",
"arguments": {
"workspace": "PROJ", // Required - your project key
"repository": "my-repo",
"pull_request_id": 123
}
}
Returns detailed information about the pull request including:
merge_commit_hash: The hash of the merge commitmerged_by: Who performed the mergemerged_at: When the merge occurredmerge_commit_message: The merge commit messageactive_comments: Array of active comments (up to 20 most recent top-level comments)
replies: Array of reply comments with same structureparent_id: ID of the parent comment for repliesactive_comment_count: Total count of unresolved comments (including nested replies)total_comment_count: Total count of all comments (including resolved and replies)file_changes: Array of all files modified in the PR
file_changes_summary: Summary statistics
{
"tool": "list_pull_requests",
"arguments": {
"workspace": "PROJ", // Required - your project key
"repository": "my-repo",
"state": "OPEN", // Optional: OPEN, MERGED, DECLINED, ALL (default: OPEN)
"author": "username", // Optional: filter by author (see note below)
"limit": 25, // Optional: max results per page (default: 25)
"start": 0 // Optional: pagination start index (default: 0)
}
}
Returns a paginated list of pull requests with:
Note on Author Filter:
{
"tool": "create_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"title": "Add new feature",
"source_branch": "feature/new-feature",
"destination_branch": "main",
"description": "This PR adds a new feature...", // Optional
"reviewers": ["john.doe", "jane.smith"], // Optional
"close_source_branch": true // Optional (default: false)
}
}
{
"tool": "update_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"title": "Updated title", // Optional
"description": "Updated description", // Optional
"destination_branch": "develop", // Optional
"reviewers": ["new.reviewer"] // Optional - see note below
}
}
Important Note on Reviewers:
reviewers parameter, existing reviewers and their approval status are preservedreviewers parameter:
Add a comment to a pull request, either as a general comment or inline on specific code:
// General comment
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "Great work on this PR!"
}
}
// Inline comment on specific line
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "Consider extracting this into a separate function",
"file_path": "src/utils/helpers.js",
"line_number": 42,
"line_type": "CONTEXT" // ADDED, REMOVED, or CONTEXT
}
}
// Reply to existing comment
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "I agree with this suggestion",
"parent_comment_id": 456
}
}
// Add comment with code suggestion (single line)
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "This variable name could be more descriptive.",
"file_path": "src/utils/helpers.js",
"line_number": 42,
"line_type": "CONTEXT",
"suggestion": "const userAuthenticationToken = token;"
}
}
// Add comment with multi-line code suggestion
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "This function could be simplified using array methods.",
"file_path": "src/utils/calculations.js",
"line_number": 50,
"suggestion_end_line": 55,
"line_type": "CONTEXT",
"suggestion": "function calculateTotal(items) {\n return items.reduce((sum, item) => sum + item.price, 0);\n}"
}
}
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 and line_number are required when using suggestionssuggestion_end_line is optional and used for multi-line suggestions (defaults to line_number)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:
// Add comment using code snippet
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "This variable name could be more descriptive",
"file_path": "src/components/Button.res",
"code_snippet": "let isDisabled = false",
"search_context": {
"before": ["let onClick = () => {"],
"after": ["setLoading(true)"]
}
}
}
// Handle multiple matches with strategy
{
"tool": "add_comment",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment_text": "Consider extracting this",
"file_path": "src/utils/helpers.js",
"code_snippet": "return result;",
"search_context": {
"before": ["const result = calculate();"],
"after": ["}"]
},
"match_strategy": "best" // Auto-select highest confidence match
}
}
Code Snippet Parameters:
code_snippet: The exact code line to find (alternative to line_number)search_context: Optional context to disambiguate multiple matches
before: Array of lines that should appear before the targetafter: Array of lines that should appear after the targetmatch_strategy: How to handle multiple matches
"strict" (default): Fail with error showing all matches"best": Auto-select the highest confidence matchError Response for Multiple Matches (strict mode):
{
"error": {
"code": "MULTIPLE_MATCHES_FOUND",
"message": "Code snippet 'return result;' found in 3 locations",
"occurrences": [
{
"line_number": 42,
"file_path": "src/utils/helpers.js",
"preview": " const result = calculate();\n> return result;\n}",
"confidence": 0.9,
"line_type": "ADDED"
},
// ... more matches
],
"suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
}
}
This feature is particularly useful for:
Note on comment replies:
parent_comment_id to reply to any comment (general or inline)get_pull_request responses:
replies arrayparent_id field for reply commentsNote 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 linesThe add_comment tool supports multiple scenarios. Here's when and how to use each approach:
1. General PR Comments (No file/line)
comment_text only2. Reply to Existing Comments
comment_text, parent_comment_id3. Inline Comments with Line Number
comment_text, file_path, line_numberline_type (defaults to CONTEXT)4. Inline Comments with Code Snippet
comment_text, file_path, code_snippetsearch_context if the code appears multiple timesmatch_strategy: "best" to auto-select when multiple matches exist5. Code Suggestions
comment_text, file_path, line_number, suggestionsuggestion_end_lineDecision Flow for AI/Automated Tools:
1. Do you want to suggest code changes?
→ Use suggestion with line_number
2. Do you have the exact line number?
→ Use line_number directly
3. Do you have the code snippet but not line number?
→ Use code_snippet (add search_context if needed)
4. Is it a general comment about the PR?
→ Use comment_text only
5. Are you replying to another comment?
→ Add parent_comment_id
Common Pitfalls to Avoid:
line_number and code_snippet - pick onefile_path and line_number{
"tool": "merge_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"merge_strategy": "squash", // Optional: merge-commit, squash, fast-forward
"close_source_branch": true, // Optional
"commit_message": "Custom merge message" // Optional
}
}
{
"tool": "list_branches",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"filter": "feature", // Optional: filter by name pattern
"limit": 25, // Optional (default: 25)
"start": 0 // Optional: for pagination (default: 0)
}
}
Returns a paginated list of branches with:
{
"tool": "delete_branch",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "feature/old-feature",
"force": false // Optional (default: false)
}
}
Note: Branch deletion requires appropriate permissions. The branch will be permanently deleted.
{
"tool": "get_branch",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"branch_name": "feature/new-feature",
"include_merged_prs": false // Optional (default: false)
}
}
Returns comprehensive branch information including:
include_merged_prs is true):
This tool is particularly useful for:
Get the diff/changes for a pull request with optional filtering capabilities:
// Get full diff (default behavior)
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"context_lines": 5 // Optional (default: 3)
}
}
// Exclude specific file types
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"exclude_patterns": ["*.lock", "*.svg", "node_modules/**", "*.min.js"]
}
}
// Include only specific file types
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"include_patterns": ["*.res", "*.resi", "src/**/*.js"]
}
}
// Get diff for a specific file only
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"file_path": "src/components/Button.res"
}
}
// Combine filters
{
"tool": "get_pull_request_diff",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"include_patterns": ["src/**/*"],
"exclude_patterns": ["*.test.js", "*.spec.js"]
}
}
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*.js, src/**/*.res, !test/**)Response includes filtering metadata:
{
"message": "Pull request diff retrieved successfully",
"pull_request_id": 123,
"diff": "..filtered diff content..",
"filter_metadata": {
"total_files": 15,
"included_files": 12,
"excluded_files": 3,
"excluded_file_list": ["package-lock.json", "logo.svg", "yarn.lock"],
"filters_applied": {
"exclude_patterns": ["*.lock", "*.svg"]
}
}
}
{
"tool": "approve_pull_request",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123
}
}
{
"tool": "request_changes",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"pull_request_id": 123,
"comment": "Please address the following issues..." // Optional
}
}
{
"tool": "list_directory_content",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"path": "src/components", // Optional (defaults to root)
"branch": "main" // Optional (defaults to default branch)
}
}
Returns directory listing with:
{
"tool": "get_file_content",
"arguments": {
"workspace": "PROJ",
"repository": "my-repo",
"file_path": "src/index.ts",
"branch": "main", // Optional (defaults to default branch)
"start_line": 1, // Optional: starting line (1-based, use negative for from end)
"line_count": 100, // Optional: number of lines to return
"full_content": false // Optional: force full content (default: false)
}
}
Smart Truncation Features:
start_line: -50 to get last 50 lines (tail functionality)full_content: true or line parametersReturns file content with:
Example responses:
// Small file - returns full content
{
"file_path": "package.json",
"branch": "main",
"size": 1234,
"encoding": "utf-8",
"content": "{\n \"name\": \"my-project\",\n ...",
"last_modified": {
"commit_id": "abc123",
"author": "John Doe",
"date": "2025-01-21T10:00:00Z"
}
}
// Large file - automatically truncated
{
"file_path": "src/components/LargeComponent.tsx",
"branch": "main",
"size": 125000,
"encoding": "utf-8",
"content": "... first 500 lines ...",
"line_info": {
"total_lines": 3500,
"returned_lines": {
"start": 1,
"end": 500
},
"truncated": true,
"message": "Showing lines 1-500 of 3500. File size: 122.1KB"
}
}
npm run dev - Watch mode for developmentnpm run build - Build the TypeScript codenpm start - Run the built serverMIT
FAQs
MCP server for Bitbucket API integration - supports both Cloud and Server
The npm package @nexus2520/bitbucket-mcp-server receives a total of 597 weekly downloads. As such, @nexus2520/bitbucket-mcp-server popularity was classified as not popular.
We found that @nexus2520/bitbucket-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.