Personal Bitbucket MCP Server

Bitbucket MCP Server Build on Top of Quarkus Framework

A Model Context Protocol (MCP) server that provides AI assistants with tools to interact with Bitbucket Cloud repositories. Built with Quarkus, the Supersonic Subatomic Java Framework.

Author:Tedy Saputro|Contact:tedy@saputro.dev

If you want to learn more about Quarkus, please visit its website:https://quarkus.io/.

- Quick Start
- MCP Tools Reference
- Configuration
- Running with Docker
- Development
- Building
- API Documentation
- Use Cases
- Troubleshooting
- Roadmap
- Contributing
- Bitbucket API Token: Create an API token athttps://bitbucket.org/account/settings/api-token/

- Required permissions:repository:read,pullrequest:read,pullrequest:write
- SeeCreating a Bitbucket API Tokenfor detailed instructions

docker run -p 8080:8080 \ -e BITBUCKET_EMAIL=your-email@example.com \ -e BITBUCKET_API_TOKEN=your-api-token \ -e BITBUCKET_WORKSPACE=your-workspace \ subrutin/bitbucket-mcp-server:latest

{ "mcpServers": { "bitbucket": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BITBUCKET_EMAIL=your-email@example.com", "-e", "BITBUCKET_API_TOKEN=your-api-token", "-e", "BITBUCKET_WORKSPACE=your-workspace", "subrutin/bitbucket-mcp-server:stdio-0.0.2" ] } } }

Restart Claude Desktop, and you'll see the Bitbucket tools available in the 🔨 tools menu.

For Cursor IDE, add to your Cursor settings (same format as Claude Desktop):

{ "mcpServers": { "bitbucket": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BITBUCKET_EMAIL=your-email@example.com", "-e", "BITBUCKET_API_TOKEN=your-api-token", "-e", "BITBUCKET_WORKSPACE=your-workspace", "subrutin/bitbucket-mcp-server:stdio-0.0.2" ] } } }

For VS Codewith MCP extension (same format):

{ "mcp.servers": { "bitbucket": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BITBUCKET_EMAIL=your-email@example.com", "-e", "BITBUCKET_API_TOKEN=your-api-token", "-e", "BITBUCKET_WORKSPACE=your-workspace", "subrutin/bitbucket-mcp-server:stdio-0.0.2" ] } } }

For other MCP clients, use the same Docker command pattern with stdio transport.

🌐 Method 2: SSE Transport (Alternative for Web-Based Clients)

The SSE transport requires the server to be running and accessible via HTTP.

docker run -d \ --name bitbucket-mcp \ -p 8080:8080 \ -e BITBUCKET_EMAIL=your-email@example.com \ -e BITBUCKET_API_TOKEN=your-api-token \ -e BITBUCKET_WORKSPACE=your-workspace \ subrutin/bitbucket-mcp-server:latest

{ "mcpServers": { "bitbucket": { "url": "http://localhost:8080/mcp/sse" } } }

Install the MCP extension and add to your settings:

{ "mcp.servers": { "bitbucket": { "url": "http://localhost:8080/mcp/sse" } } }

- Go to Settings
- Select MCP
- Click Button Create

"Type": sse "url": "http://localhost:8080/mcp/sse", "name": "Bitbucket MCP"

-

✅stdio- Direct process communication (Universal - Recommended)

- Works with: ALL MCP clients(Claude Desktop, Cursor, VS Code, Cherry Studio, etc.)
- No HTTP server needed
- Simplest setup
- Use image:subrutin/bitbucket-mcp-server:stdio-0.0.2

✅SSE (Server-Sent Events)- HTTP-based transport

- Alternative option for web-based clients
- Requires running HTTP server
- Long-lived connections
- Real-time updates
- Use image:subrutin/bitbucket-mcp-server:latest

- Request/response patterns
- Programmatic access
- Use image:subrutin/bitbucket-mcp-server:latest

- Currently only HTTP available for SSE
- HTTPS support planned for future release

This server provides 11 tools for interacting with Bitbucket:

Returns all pull requests on the specified repository.

- workspace(string): The workspace ID or slug where the repository is located
- reposlug(string): The repository slug or name to get pull requests from

Use the findAllPullRequest tool with workspace "myteam" and reposlug "myrepo"

Returns a specific pull request by ID with detailed information.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- pullRequestId(integer): The pull request ID to get details from

Get details of pull request #42 from myteam/myrepo

Returns the diffstat (statistics about changes) for a pull request.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- id(integer): The pull request ID

Returns the actual diff/changes in a pull request, showing added/removed lines.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- id(integer): The pull request ID

Creates a general comment on a pull request.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- pullRequestId(integer): The pull request ID to comment on
- commentText(string): The comment text content (supports Markdown)

Add a comment to PR #42 saying "LGTM! Great work on the refactoring."

Updates an existing comment on a pull request.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- pullRequestId(integer): The pull request ID
- commentId(integer): The comment ID to update
- commentText(string): The updated comment text content

Update comment #123 on PR #42 with new text

Creates an inline comment on a specific line of code in a pull request diff.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- pullRequestId(integer): The pull request ID
- filePath(string): The EXACT file path as shown in the PR diff (case-sensitive)
- lineNumber(integer): The line number in the NEW version of the file
- commentText(string): The comment text in Markdown format

- ThefilePathmust EXACTLY match the file path shown in the PR diff
- ThelineNumbermust be from the NEW/MODIFIED version (lines with '+' in diff)
- The line must exist in the PR diff - you cannot comment on unchanged lines
- Workflow: First callfindListChangesInAPullRequestto get the diff, then identify the correct file path and line number

First, get the diff for PR #42, then add an inline comment on line 25 of src/main/java/Service.java

Returns a specific pull request comment with its details.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- pullRequestId(integer): The pull request ID
- commentId(integer): The comment ID to retrieve

Returns a paginated list of comments for a specific pull request.

- workspace(string): The workspace ID or slug
- reposlug(string): The repository slug
- pullRequestId(integer): The pull request ID
- page(integer): The page number for pagination
- pageLength(integer): The number of items per page
- size(integer): The total number of items

Returns the authenticated user's Bitbucket profile information.

This server requires the following environment variables for authentication with Bitbucket Cloud:
- Go tohttps://bitbucket.org/account/settings/api-token/
- Click "Create API token"
- Give it a label (e.g., "MCP Server")
- Select permissions:

Note:API tokens are different from app passwords. API tokens provide more granular permissions and are the recommended authentication method. For more information, seeAtlassian's API Token documentation.

bitbucket: api: email: ${BITBUCKET_EMAIL:} token: ${BITBUCKET_API_TOKEN:} workspace: ${BITBUCKET_WORKSPACE:} quarkus: rest-client: bitbucket-api: url: https://api.bitbucket.org/2.0

- Will enable secure SSE connections
- SSL certificate configuration needed
- SeeRoadmapfor timeline

- For ALL MCP clients (Claude Desktop, Cursor, VS Code, Cherry Studio, etc.)
- Direct process communication
- No HTTP server needed
- Simplest setup