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
  • Docker (Recommended)
  • Local Development
• Configuration
  • Environment Variables
  • MCP Client Setup
• Transport Options
  • Standard I/O Transport (Default)
  • HTTP Streaming Transport
• Security
  • API Key Authentication
• 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

1. Clone the Repository:

   git clone https://github.com/n11tech/mcp-bitbucket.git
   cd mcp-bitbucket

2. Build the Docker Image:

   docker build -t mcp-bitbucket:latest .

3. 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

1. Clone and Install:

   git clone https://github.com/n11tech/mcp-bitbucket.git
   cd mcp-bitbucket
   npm install

2. Build:

   npm run build

3. Start:

   npm start

Using This MCP Server with Smithery CLI

You can use this Bitbucket MCP server locally with the Smithery CLI. This allows you to connect your AI tools or agents to your self-hosted Bitbucket Server/Data Center. This server is not hosted on Smithery AI cloud; you must run it yourself (locally or on your own server).

Prerequisites

• Node.js 18 or higher
• Smithery CLI

1. Install Smithery CLI

npm install -g @smithery/cli

2. Start the Bitbucket MCP Server Locally

You must run your own instance of the server (Docker recommended):

docker run -it --rm \
  -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="/mcp" \
  -p 3001:3001 \
  ghcr.io/n11tech/mcp-bitbucket:latest

Or, using npm:

npm run start:http

3. Connect to Your Local MCP Server with Smithery CLI

Once your server is running locally, connect to it using the local address:

npx @smithery/cli connect http://localhost:3001/mcp

4. Example: Using with Smithery CLI

Once connected, you can call tools (e.g., list repositories):

npx @smithery/cli call http://localhost:3001/mcp bitbucket_list_repositories --params '{"workspaceSlug": "your-workspace"}'

For more details, see the Smithery CLI documentation.

Note for Smithery Users:

When connecting to this MCP server via Smithery, you only need to provide:

• Bitbucket Server URL (e.g., <your-bitbucket-url>)
• Bitbucket Personal Access Token

All other environment variables (such as port, endpoint, API key) are managed by the server administrator or deployment and do not need to be set by end users.

If the server administrator has enabled API key authentication, you may be asked to provide an API key as well. In that case, enter the value provided by your admin.

Example:

When prompted by Smithery, enter:

bitbucketUrl: <your-bitbucket-url>
bitbucketToken: <your-bitbucket-token>

Advanced: Using STDIO Transport

By default, this MCP server is configured for HTTP transport, which is recommended for most users and for Smithery CLI/web integrations.

Advanced users who want to run the MCP server as a local subprocess (STDIO transport) can use the following Smithery configuration:

startCommand:
  type: "stdio"
  configSchema:
    type: "object"
    required: ["bitbucketUrl", "bitbucketToken"]
    properties:
      bitbucketUrl:
        type: "string"
        description: "The base URL of your self-hosted Bitbucket instance (e.g., https://<your-bitbucket-url>)"
      bitbucketToken:
        type: "string"
        description: "Personal Access Token for Bitbucket Server/Data Center"
  commandFunction: |-
    (config) => ({
      command: 'node',
      args: ['build/infrastructure/index.js'],
      env: {
        BITBUCKET_URL: config.bitbucketUrl,
        BITBUCKET_TOKEN: config.bitbucketToken
      }
    })
  exampleConfig:
    bitbucketUrl: "https://<your-bitbucket-url>"
    bitbucketToken: "<your-bitbucket-token>"

This allows you to launch the MCP server as a subprocess and communicate via standard input/output, which may be useful for certain local agent or automation scenarios.

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="mcp" \
  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": "mcp"
      }
    }
  }
}

HTTP Endpoints:

• POST http://localhost:3001/mcp - Send MCP requests
• GET http://localhost:3001/mcp - 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 requests
• bitbucket_get_pull_request_details - Get PR details and metadata
• bitbucket_get_pull_request_diff - Retrieve PR diffs
• bitbucket_get_pull_request_reviews - Get PR review status
• bitbucket_merge_pull_request - Merge pull requests
• bitbucket_decline_pull_request - Decline pull requests
• bitbucket_add_pull_request_comment - Add general PR comments

Repository Operations

• bitbucket_list_workspaces - List available workspaces
• bitbucket_list_repositories - Browse repositories
• bitbucket_get_repository_details - Get repository information
• bitbucket_search_content - Search within repositories
• bitbucket_get_file_content - Read file contents

Branch Management

• bitbucket_create_branch - Create new branches
• bitbucket_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