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.

Version 2.1.0 Release Notes

Approval Tool & Security Hardening (June 2026)

This minor release adds pull request approval support and includes non-breaking security and maintainability improvements.

✨ New Features

• Pull Request Approval Tool: Added bitbucket_approve_pull_request tool backed by Bitbucket Server/Data Center approve endpoint semantics.

🔒 Security & Reliability

• Input/Path Safety Improvements: Strengthened schema and path-handling behavior in core request flows.
• HTTP Transport Hardening: Improved authentication/session behavior for safer HTTP streaming operation.
• Logging Hygiene: Reduced sensitive argument exposure by using safer request argument summaries.

⚠️ Breaking Changes

None - changes are backward compatible.

---

Version 2.0.0 Release Notes

Major Core Refactor & Transport Alignment (June 2026)

This major release reflects substantial changes in the core architecture and runtime behavior of the server to improve maintainability, consistency, and protocol alignment for Bitbucket-focused deployments.

✨ Core Improvements

• Core Application Refactor: Internal layering and wiring were reorganized around cleaner boundaries across application, domain, and infrastructure modules.
• MCP SDK HTTP Streaming Model Adoption: The transport/session lifecycle now follows MCP SDK's StreamableHTTPServerTransport pattern instead of a fully custom session-management flow.
• HTTP Streaming Stabilization: Session lifecycle handling was improved for initialize/connect/close flows and more predictable session cleanup.
• Bitbucket Service Identity Cleanup: Runtime logs and service naming were aligned to Bitbucket terminology.
• Type-Safety Hardening: Core infrastructure paths use stricter typing and safer error handling patterns.

📦 Runtime & Dependency Updates

• Node.js Runtime Baseline Updated: Runtime expectations were refreshed; use the version declared in package.json under engines.
• Dependency Refresh: Core/runtime and development dependencies were upgraded to newer versions for compatibility, security, and maintainability.

⚠️ Breaking Changes

• Major Version Bump: Package version moved to 2.0.0 to reflect core-level changes.
• Package Rename: NPM package metadata now uses mcp-bitbucket.

Migration Notes

• If you pin package metadata or release automation to the old package name, update it to mcp-bitbucket.
• HTTP transport internals now align with MCP SDK session semantics; if you depended on custom session handling behavior, re-validate your client integration.
• HTTP startup command remains available as npm run start:http; npm run start:http-streaming is kept as a compatibility alias.
• Reinstall dependencies after upgrade to pick up new transitive versions (rm -rf node_modules && npm install).

---

Version 1.2.0 Release Notes

LLM Compatibility: Google Gemini Schema Sanitizer (May 2026)

This release fixes a known interoperability issue where Google Gemini-based MCP clients (e.g. n8n MCP Client with Gemini, Vertex AI function calling) reject tool schemas emitted by this server.

✨ New Features

• Gemini-Compatible tools/list Output: Tool inputSchema payloads are now normalized server-side so they validate against Gemini's stricter JSON Schema subset.
  • JSON Schema unions expressed as type: ["string", "null"] are automatically rewritten to anyOf: [{type: "string"}, {type: "null"}].
  • Anthropic Claude and OpenAI ChatGPT clients are unaffected (the rewritten form is semantically equivalent and natively supported).
  • Eliminates the need for downstream workarounds such as n8n Code-node sanitizers.

🔒 Security Hardening

• Prototype Pollution Defense: Schema sanitizer skips __proto__, prototype, and constructor keys and uses Object.create(null) as the recursion accumulator.
• Recursion Depth Cap: Sanitizer bounds recursion at depth 64 to prevent stack-overflow DoS on hostile or cyclic schema input.
• Pure Transformation: Sanitizer never mutates caller input and performs no I/O, logging, or credential handling.

📚 Documentation

• Documented Gemini interoperability fix in release notes.

⚠️ Breaking Changes

None - all changes are backward compatible.

---

Version 1.1.0 Release Notes

New Feature: Directory Browsing & Security Fix (April 2026)

This release adds directory browsing capabilities and fixes a critical path traversal vulnerability:

✨ New Features

• Directory Browsing Tool: Added bitbucket_browse_directory tool for exploring repository structure
  • Browse root directory with empty path, ., or /
  • Navigate subdirectories efficiently
  • Returns file/folder metadata without fetching content (lightweight operation)
  • Enables AI agents to discover repository structure autonomously
  • Resolves Issue #2

🔒 Security Fixes

• CRITICAL: Fixed path traversal vulnerability in browseBitbucketDirectory path parameter
  • Added validation to block .. sequences (path traversal prevention)
  • Added control character filtering to prevent null byte injection
  • Added path length limits (max 1000 characters) to prevent DoS attacks
  • Multi-layer defense: schema validation + URL encoding + API-level checks

📚 Documentation

• Added bitbucket_browse_directory tool to Available Tools section
• Updated security documentation with path validation details

⚠️ Breaking Changes

None - all changes are backward compatible.

---

Version 1.0.1 Release Notes

Security Improvements & Bug Fixes (February 2026)

This release includes critical security enhancements and implements the BITBUCKET_DEFAULT_PROJECT feature:

🔒 Security Enhancements

• Input Validation: Added strict regex validation for project keys and workspace slugs to prevent path traversal and injection attacks
• URL Encoding: All API path parameters are now properly URL-encoded to prevent path manipulation
• Environment Variable Validation: BITBUCKET_DEFAULT_PROJECT is validated and sanitized before use
• Comprehensive Security Tests: Added extensive test coverage for path traversal, SQL injection, command injection, and DoS attacks

🐛 Bug Fixes

• Fixed: BITBUCKET_DEFAULT_PROJECT environment variable was being ignored (PR #1)
• Fixed: getDefaultProjectKey() method now properly returns the configured default project instead of always returning undefined

📚 Documentation

• Added security notes for BITBUCKET_DEFAULT_PROJECT configuration
• Documented valid and invalid project key formats
• Added multi-tenant environment warnings

⚠️ Breaking Changes

None - all changes are backward compatible.

---

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 defined by package.json engines (currently >=18)
• 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 version defined by package.json engines (currently >=18)
• 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	-	✅
BITBUCKET_DEFAULT_PROJECT	Default project key for operations (see Security Notes below)	-	❌
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	-	❌

Security Notes for BITBUCKET_DEFAULT_PROJECT

⚠️ Important Security Considerations:

• Input Validation: The BITBUCKET_DEFAULT_PROJECT value is automatically validated to prevent path traversal and injection attacks. Only alphanumeric characters, hyphens, and underscores are allowed.
• Multi-Tenant Environments: In shared or multi-tenant deployments, be aware that the default project applies globally to all requests that don't specify a workspaceSlug. Consider using explicit workspace slugs in API calls instead.
• Valid Format: Project keys must match the pattern ^[A-Z0-9_-]+$ (case-insensitive) and be between 1-255 characters.
• Invalid Values: If an invalid project key is provided, the server will log an error and ignore the value, requiring explicit workspaceSlug in all API calls.

Example Valid Values:

BITBUCKET_DEFAULT_PROJECT=MYPROJECT
BITBUCKET_DEFAULT_PROJECT=my-project-123
BITBUCKET_DEFAULT_PROJECT=TEAM_ALPHA

Example Invalid Values (will be rejected):

BITBUCKET_DEFAULT_PROJECT=../../../admin  # Path traversal attempt
BITBUCKET_DEFAULT_PROJECT=PROJ; rm -rf /  # Command injection attempt
BITBUCKET_DEFAULT_PROJECT=PROJ/test       # Contains invalid character

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 gateway 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_approve_pull_request - Approve pull requests
• 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
• bitbucket_browse_directory - Browse directory contents (returns file/folder metadata without content)

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