n11tech/mcp-bitbucket
If you are the rightful owner of mcp-bitbucket and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The MCP Bitbucket server is a Node.js/TypeScript application designed to facilitate secure interactions between AI systems and Atlassian Bitbucket Server/Data Center.
mcp-bitbucket
A Node.js/TypeScript Model Context Protocol (MCP) server for Atlassian Bitbucket Server/Data Center.
This server enables AI systems (e.g., LLMs, AI coding assistants) to securely interact with your self-hosted Bitbucket repositories, pull requests, projects, and code in real time through both standard stdio and HTTP streaming transports.
Table of Contents
- Features
- What is MCP?
- Prerequisites
- Installation
- Configuration
- Transport Options
- Security
- Usage Examples
- Available Tools
- Development
- License
Features
- Dual Transport Support: Choose between stdio and HTTP streaming transports
- Secure Authentication: Optional API key authentication for HTTP transport
- Comprehensive Bitbucket Integration: Full access to Bitbucket Server/Data Center APIs
- Developer Focused: Designed to help AI assistants understand and interact with your codebase
- Production Ready: Built with TypeScript, proper error handling, and security best practices
- Container Support: Docker support for easy deployment and scaling
What is MCP?
Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This server implements MCP for Bitbucket Server/Data Center, enabling AI assistants to interact with your Bitbucket data programmatically through standardized interfaces.
Prerequisites
- Node.js: Version 18.x or higher
- Bitbucket Server/Data Center: Access with a Personal Access Token (PAT)
- Docker: (Recommended) For containerized deployment
- Git: For cloning the repository
Installation
Docker (Recommended)
Using Pre-built Image from GHCR
Pull and run the latest image:
# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/n11tech/mcp-bitbucket:latest
# Run with environment variables
docker run -i --rm \
-e BITBUCKET_URL="https://your-bitbucket-server.com" \
-e BITBUCKET_TOKEN="your_personal_access_token" \
ghcr.io/n11tech/mcp-bitbucket:latest
Building from Source
-
Clone the Repository:
git clone https://github.com/n11tech/mcp-bitbucket.git cd mcp-bitbucket
-
Build the Docker Image:
docker build -t mcp-bitbucket:latest .
-
Run with Docker:
docker run -i --rm \ -e BITBUCKET_URL="https://your-bitbucket-server.com" \ -e BITBUCKET_TOKEN="your_personal_access_token" \ mcp-bitbucket:latest
Local Development
-
Clone and Install:
git clone https://github.com/n11tech/mcp-bitbucket.git cd mcp-bitbucket npm install
-
Build:
npm run build
-
Start:
npm start
Configuration
Environment Variables
Variable | Description | Default | Required |
---|---|---|---|
BITBUCKET_URL | Your Bitbucket Server/Data Center URL | - | ā |
BITBUCKET_TOKEN | Personal Access Token | - | ā |
ENABLE_HTTP_TRANSPORT | Enable HTTP streaming transport | false | ā |
MCP_HTTP_PORT | HTTP server port | 3001 | ā |
MCP_HTTP_ENDPOINT | HTTP endpoint path | /stream | ā |
MCP_API_KEY | API key for authentication | - | ā |
MCP Client Setup
Configure your MCP-compatible client to connect to this server. The configuration depends on your chosen transport method.
Transport Options
Standard I/O Transport (Default)
The default transport method uses standard input/output for communication. This is suitable for direct integration with AI systems that launch the server as a child process.
Example MCP Configuration:
{
"mcpServers": {
"mcp-bitbucket": {
"command": "docker",
"args": [
"run", "-i", "--rm", "--network=host",
"-e", "BITBUCKET_URL",
"-e", "BITBUCKET_TOKEN",
"ghcr.io/n11tech/mcp-bitbucket:latest"
],
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your_personal_access_token"
}
}
}
}
HTTP Streaming Transport
For scenarios requiring remote connections or web-based integrations, the server supports HTTP streaming transport with Server-Sent Events (SSE).
Enable HTTP Transport:
# Using GHCR image
docker run -i --rm \
-p 3001:3001 \
-e BITBUCKET_URL="https://your-bitbucket-server.com" \
-e BITBUCKET_TOKEN="your_personal_access_token" \
-e ENABLE_HTTP_TRANSPORT="true" \
-e MCP_HTTP_PORT="3001" \
-e MCP_HTTP_ENDPOINT="stream" \
ghcr.io/n11tech/mcp-bitbucket:latest
# Using npm script
npm run start:http
Example MCP Configuration for HTTP Transport:
{
"mcpServers": {
"mcp-bitbucket": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-p", "3001:3001",
"-e", "BITBUCKET_URL",
"-e", "BITBUCKET_TOKEN",
"-e", "ENABLE_HTTP_TRANSPORT",
"-e", "MCP_HTTP_PORT",
"-e", "MCP_HTTP_ENDPOINT",
"ghcr.io/n11tech/mcp-bitbucket:latest"
],
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your_personal_access_token",
"ENABLE_HTTP_TRANSPORT": "true",
"MCP_HTTP_PORT": "3001",
"MCP_HTTP_ENDPOINT": "stream"
}
}
}
}
HTTP Endpoints:
- POST
http://localhost:3001/stream
- Send MCP requests - GET
http://localhost:3001/stream
- Server-Sent Events stream - GET
http://localhost:3001/health
- Health check endpoint
Security
API Key Authentication
For HTTP transport, you can enable API key authentication to secure your server:
Setup API Key Authentication:
# Generate a secure API key (recommended: 32+ characters)
export MCP_API_KEY="your-secure-api-key-here"
# Run with authentication enabled
docker run -i --rm \
-p 3001:3001 \
-e BITBUCKET_URL="https://your-bitbucket-server.com" \
-e BITBUCKET_TOKEN="your_personal_access_token" \
-e ENABLE_HTTP_TRANSPORT="true" \
-e MCP_API_KEY="your-secure-api-key-here" \
mcp-bitbucket:latest
Configuration with API Key:
{
"mcpServers": {
"mcp-bitbucket": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-p", "3001:3001",
"-e", "BITBUCKET_URL",
"-e", "BITBUCKET_TOKEN",
"-e", "ENABLE_HTTP_TRANSPORT",
"-e", "MCP_API_KEY",
"mcp-bitbucket:latest"
],
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_TOKEN": "your_personal_access_token",
"ENABLE_HTTP_TRANSPORT": "true",
"MCP_API_KEY": "your-secure-api-key-here"
}
}
}
}
When API key authentication is enabled, all HTTP requests must include the API key in the request headers or parameters.
Usage Examples
Pull Request Management
// Create a pull request
await callTool('bitbucket_create_pull_request', {
repository: 'my-repo',
title: 'Feature: Add new API endpoint',
sourceBranch: 'feature/api-endpoint',
targetBranch: 'main',
description: 'This PR adds a new REST API endpoint for user management.'
});
// Get pull request details
await callTool('bitbucket_get_pull_request_details', {
repository: 'my-repo',
prId: 123
});
Repository Operations
// Search repository content
await callTool('bitbucket_search_content', {
workspaceSlug: 'my-workspace',
query: 'authentication',
extension: 'js'
});
// Get file content
await callTool('bitbucket_get_file_content', {
workspaceSlug: 'my-workspace',
repoSlug: 'my-repo',
filePath: 'src/auth/login.js'
});
Available Tools
This server provides a comprehensive suite of tools for interacting with Bitbucket Server/Data Center:
Pull Request Management
bitbucket_create_pull_request
- Create new pull requestsbitbucket_get_pull_request_details
- Get PR details and metadatabitbucket_get_pull_request_diff
- Retrieve PR diffsbitbucket_get_pull_request_reviews
- Get PR review statusbitbucket_merge_pull_request
- Merge pull requestsbitbucket_decline_pull_request
- Decline pull requestsbitbucket_add_pull_request_comment
- Add general PR comments
Repository Operations
bitbucket_list_workspaces
- List available workspacesbitbucket_list_repositories
- Browse repositoriesbitbucket_get_repository_details
- Get repository informationbitbucket_search_content
- Search within repositoriesbitbucket_get_file_content
- Read file contents
Branch Management
bitbucket_create_branch
- Create new branchesbitbucket_list_repository_branches
- List repository branches
User Management
bitbucket_get_user_profile
- Get user profile details
For detailed parameter information and usage examples, refer to the individual tool schemas in src/domain/contracts/schemas/
.
Development
Available Scripts
- Build:
npm run build
- Compile TypeScript to JavaScript - Start:
npm start
- Run the server with stdio transport - HTTP:
npm run start:http
- Run with HTTP streaming transport - Development:
npm run dev
- Watch mode for development - Lint:
npm run lint
- Code quality checks - Test:
npm run test
- Run test suite - Inspector:
npm run inspector
- Debug MCP server interactions
Development Setup
# Clone and setup
git clone <repository_url>
cd mcp-bitbucket
npm install
# Create environment file
cp .env.example .env
# Edit .env with your Bitbucket credentials
# Development with watch mode
npm run dev
Architecture
The codebase follows clean architecture principles:
src/
āāā application/ # Application layer
ā āāā facade/ # Client facades
ā āāā use-cases/ # Business logic
āāā domain/ # Domain layer
ā āāā contracts/ # Interfaces and schemas
ā āāā entity/ # Domain entities
ā āāā repository/ # Repository interfaces
āāā infrastructure/ # Infrastructure layer
ā āāā clients/ # External API clients
ā āāā config/ # Configuration management
ā āāā http/ # HTTP transport implementation
ā āāā setup/ # Server setup and initialization
License
This project is licensed under the Apache License, Version 2.0.
See the LICENSE
file for more details.
Built with the Model Context Protocol