Skip to main content
Glama

Bitbucket MCP Server

by pdogra1299
npmGitHub
TypeScript
MIT License
138
3
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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 request
  • list_pull_requests - List pull requests with filters (state, author, pagination)
  • create_pull_request - Create new pull requests
  • update_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 strategies
  • delete_branch - Delete branches after merge
Branch Management Tools
  • list_branches - List branches with filtering and pagination
  • delete_branch - Delete branches (with protection checks)
  • get_branch - Get detailed branch information including associated PRs
File and Directory Tools
  • list_directory_content - List files and directories in a repository path
  • get_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 request
  • approve_pull_request - Approve a pull request
  • unapprove_pull_request - Remove approval from a pull request
  • request_changes - Request changes on a pull request
  • remove_requested_changes - Remove change request from a pull request

Installation

The 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" } } } }

From Source

  1. Clone or download this repository
  2. Install dependencies:
    npm install
  3. Build the TypeScript code:
    npm run build

Authentication Setup

This server uses Bitbucket App Passwords for authentication.

Creating an App Password

  1. Log in to your Bitbucket account
  2. Navigate to: https://bitbucket.org/account/settings/app-passwords/
  3. Click "Create app password"
  4. Give it a descriptive label (e.g., "MCP Server")
  5. Select the following permissions:
    • Account: Read
    • Repositories: Read, Write
    • Pull requests: Read, Write
  6. Click "Create"
  7. Important: Copy the generated password immediately (you won't be able to see it again!)

Running the Setup Script

node scripts/setup-auth.js

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):

{ "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 directory
  • your-username with your Bitbucket username (not email)
  • your-app-password with the app password you created

For 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:

  • 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

{ "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:

  • 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 commit
    • merged_by: Who performed the merge
    • merged_at: When the merge occurred
    • merge_commit_message: The merge commit message
  • And more...

List Pull Requests

{ "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:

  • 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

{ "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) } }

Update Pull Request

{ "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 - replaces existing reviewers } }

Add Comment

Add general comments or inline comments on specific lines of code:

// General comment { "tool": "add_comment", "arguments": { "workspace": "PROJ", "repository": "my-repo", "pull_request_id": 123, "comment_text": "Great work! Just one small suggestion...", "parent_comment_id": 456 // Optional - for replies } } // Inline comment on specific code { "tool": "add_comment", "arguments": { "workspace": "PROJ", "repository": "my-repo", "pull_request_id": 123, "comment_text": "This variable should be renamed for clarity", "file_path": "src/main.js", "line_number": 42, "line_type": "ADDED" // ADDED, REMOVED, or CONTEXT } }

Note on inline comments:

  • file_path: The path to the file as shown in the diff
  • line_number: The line number as shown in the diff
  • line_type:
    • ADDED - For newly added lines (green in diff)
    • REMOVED - For deleted lines (red in diff)
    • CONTEXT - For unchanged context lines

Merge Pull Request

{ "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 } }

List Branches

{ "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:

  • Branch name and ID
  • Latest commit hash
  • Default branch indicator
  • Pagination info

Delete Branch

{ "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.

Get Branch

{ "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:

  • 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

Get Pull Request Diff

{ "tool": "get_pull_request_diff", "arguments": { "workspace": "PROJ", "repository": "my-repo", "pull_request_id": 123, "context_lines": 5 // Optional (default: 3) } }

Approve Pull Request

{ "tool": "approve_pull_request", "arguments": { "workspace": "PROJ", "repository": "my-repo", "pull_request_id": 123 } }

Request Changes

{ "tool": "request_changes", "arguments": { "workspace": "PROJ", "repository": "my-repo", "pull_request_id": 123, "comment": "Please address the following issues..." // Optional } }

List Directory Content

{ "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:

  • Path and branch information
  • Array of contents with:
    • Name
    • Type (file or directory)
    • Size (for files)
    • Full path
  • Total items count

Get File Content

{ "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:

  • 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:

// 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" } }

Development

  • npm run dev - Watch mode for development
  • npm run build - Build the TypeScript code
  • npm start - Run the built server

Troubleshooting

  1. Authentication errors: Double-check your username and app password
  2. 404 errors: Verify the workspace, repository slug, and PR ID
  3. Permission errors: Ensure your app password has the required permissions

License

MIT

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

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

View all 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.

  1. Features
    1. Currently Implemented Tools
  2. Installation
    1. Using npx (Recommended)
    2. From Source
  3. Authentication Setup
    1. Creating an App Password
    2. Running the Setup Script
  4. Configuration
    1. Usage
      1. Get Pull Request
      2. List Pull Requests
      3. Create Pull Request
      4. Update Pull Request
      5. Add Comment
      6. Merge Pull Request
      7. List Branches
      8. Delete Branch
      9. Get Branch
      10. Get Pull Request Diff
      11. Approve Pull Request
      12. Request Changes
      13. List Directory Content
      14. Get File Content
    2. Development
      1. Troubleshooting
        1. License

          Related MCP Servers

          • MCP Server

            la-rebelion
            -
            security
            A
            license
            -
            quality
            MCP 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 -
            4
            3
            TypeScript
            MIT License

          • MCP Server

            agentico-dev
            -
            security
            A
            license
            -
            quality
            MCP Server provides a simpler API to interact with the Model Context Protocol by allowing users to define custom tools and services to streamline workflows and processes.
            Last updated -
            13
            2
            TypeScript
            MIT License

          • Bitbucket Server MCP

            garc33
            A
            security
            A
            license
            A
            quality
            Facilitates 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 -
            7
            18
            JavaScript
            Apache 2.0

          • Bitbucket MCP

            MatanYemini
            A
            security
            A
            license
            A
            quality
            A 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 -
            3
            73
            4
            JavaScript
            MIT License
            • Linux
            • Apple

          View all related MCP servers

          Appeared in Searches

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/pdogra1299/bitbucket-mcp-server'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server