bitbucket

This Bitbucket MCP Server provides AI-assisted access to Bitbucket Cloud data through a suite of MCP tools. It exposes capabilities to browse repositories, review pull requests, inspect and manage comments and tasks, view diffs and pipelines, and discover PRs awaiting review, all via natural language prompts to your AI assistant. The server is designed to be used with Claude Code, VS Code GitHub Copilot, and Cursor, enabling you to issue natural language requests that are translated into Bitbucket API calls and returned in concise, actionable responses.

To connect, you configure the MCP server through your preferred assistant integration (Claude Code, VS Code, or Cursor) and supply your Bitbucket credentials via environment variables. For Claude Code, you can add the server with the uvx command, or embed the configuration in a JSON file used by your environment. The available tools span repositories, pull requests, comments, tasks, diffs, pipelines, and more, enabling you to perform complex interactions such as fetching PR details, commenting on PRs, creating or updating tasks, and reviewing pipelines, all with reduced verbosity to save token usage.

Examples include listing repositories, retrieving pull requests for a workspace, creating a draft pull request, or fetching the status of a pipeline run. Use the provided environment variables to securely supply your Bitbucket credentials, or opt for a system keychain approach as described in the credentials section of the README. The server’s capabilities are organized into categories (Repositories, Pull Requests, Comments, Tasks PR, Diff / Review, PR Discovery, Build / CI, Pipelines, Reviewers, Draft PR, Batch Review, and Review Summary) for easy discovery and use by your AI assistant.

Prerequisites:

• Python 3.12+ is required
• Bitbucket API token with appropriate scopes (e.g., Repositories: Read, Pull requests: Read/Write)
• Python package installer (pip) and a Python environment
• Optional: uvx (the MCP runner) installed via pip or uvx installation method

Step-by-step installation:

1. Prepare your environment

   • Ensure Python 3.12+ is installed
   • Create a virtual environment (recommended): python3 -m venv venv source venv/bin/activate

2. Install the MCP server package

   • Preferred (latest version via uvx): uvx --from bitbucket-mcp-py bitbucket-mcp

   • Alternative (pip global): pip install bitbucket-mcp-py

3. Configure credentials

   • Set environment variables (preferred): export BITBUCKET_USERNAME=your-email@example.com export BITBUCKET_TOKEN=your-api-token export BITBUCKET_WORKSPACE=your-workspace

4. Run the server (via uvx)

   • Example command (from the Quick Start): uvx --from bitbucket-mcp-py bitbucket-mcp

5. Optional Docker-based running

   • Build and run the Docker image: docker build -t bitbucket-mcp-py . docker run -d --name bitbucket-mcp --env-file .env bitbucket-mcp-py

Notes:

• If using PyPI package named bitbucket-mcp-py, the entry point is bitbucket-mcp; use --from to specify the package version when using uvx.
• You can disable or enable specific tools via config files like configs/tools.json as described in the repository documentation.
• For credentials, you can also use a .env file or system keychain as described in the README.

Tips and tips:

• Use a scoped Bitbucket API token to minimize permissions and security risks.
• The Docker alternative demonstrates how to run the server in a container and expose interactions to an external AI assistant via docker exec with stdio transport.
• The MCP server supports 45 tools across multiple categories; if a tool is disabled by default, you can enable it in configs/tools.json. Remember to supply the required environment variables for authentication.
• If you encounter token/token-scopes issues, regenerate a token with the minimum necessary scopes and ensure you are using a workspace-scoped token.
• This server is designed to be used with Claude Code, VS Code Copilot, and Cursor, but any MCP-compatible AI assistant should be able to interface via stdio transport.