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.

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

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
```

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

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github/workflows		.github/workflows
docs		docs
src		src
tests		tests
.eslintrc.cjs		.eslintrc.cjs
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
config.template.env		config.template.env
jest.config.js		jest.config.js
package.json		package.json
smitheryai.yml		smitheryai.yml
tsconfig.json		tsconfig.json

License

n11tech/mcp-bitbucket

Folders and files

Latest commit

History

Repository files navigation

mcp-bitbucket

Table of Contents

Features

What is MCP?

Prerequisites

Installation

Docker (Recommended)

Using Pre-built Image from GHCR

Building from Source

Local Development

Using This MCP Server with Smithery CLI

Prerequisites

1. Install Smithery CLI

2. Start the Bitbucket MCP Server Locally

3. Connect to Your Local MCP Server with Smithery CLI

4. Example: Using with Smithery CLI

Advanced: Using STDIO Transport

Configuration

Environment Variables

MCP Client Setup

Transport Options

Standard I/O Transport (Default)

HTTP Streaming Transport

Security

API Key Authentication

Usage Examples

Pull Request Management

Repository Operations

Available Tools

Pull Request Management

Repository Operations

Branch Management

User Management

Development

Available Scripts

Development Setup

Architecture

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages