Atlassian Bitbucket MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Atlassian Bitbucket for pull request reviews, code search, and repository operations.

Features

• Pull Request Management: Review PRs, add/resolve comments, approve changes
• Code Search: Search code across repositories and commits
• Repository Operations: List repos, browse branches, view file content
• Dual Instance Support: Works with both Bitbucket Cloud and self-hosted Data Center/Server
• Secure: Built with security in mind, avoiding compromised npm packages
• Type-Safe: Full TypeScript implementation with strict type checking
• Caching: Smart caching layer for frequently accessed static data
• Local-First: Designed for NPX-based local usage with Personal Access Tokens

Requirements

• Node.js >= 20.0.0
• pnpm (recommended) or npm/yarn
• Bitbucket Personal Access Token (Cloud or Server/Data Center)
• Access to a Bitbucket instance (Cloud or self-hosted)

Quick Start

1. Environment Setup

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and set the required variables:

BITBUCKET_URL=https://bitbucket.org # or your self-hosted URL
BITBUCKET_TOKEN=your_personal_access_token
BITBUCKET_DEFAULT_PROJECT=PROJ # your default project key

2. Installation

pnpm install

3. Build

pnpm run build

4. Usage with MCP Client

Configure your MCP client (e.g., Claude Desktop) to use this server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "atlassian-bitbucket-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.org",
        "BITBUCKET_TOKEN": "your_token_here",
        "BITBUCKET_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}

Configuration

Environment Variables

All configuration is done through environment variables. See .env.example for the complete list.

Required

• BITBUCKET_URL - Your Bitbucket instance URL
• BITBUCKET_TOKEN - Personal Access Token
• BITBUCKET_DEFAULT_PROJECT - Default project key

Optional

• BITBUCKET_ALLOWED_ACTIONS - Comma-separated list of allowed tool actions
• BITBUCKET_CACHE_ENABLED - Enable/disable caching (default: true)
• BITBUCKET_CACHE_TTL_REPOS - Repository cache TTL in seconds (default: 3600)
• See .env.example for all options

Creating a Personal Access Token

Bitbucket Cloud

1. Go to Personal settings > Personal Access Tokens
2. Click Create token
3. Give it a name and select permissions:
   • Repositories: Read, Write
   • Pull requests: Read, Write
4. Click Create and copy the token

Bitbucket Server/Data Center

1. Go to Profile > Manage account > Personal access tokens
2. Click Create a token
3. Give it a name and select permissions:
   • Project permissions: Read
   • Repository permissions: Read, Write
4. Click Create and copy the token

Available MCP Tools

This server provides the following tools for interacting with Bitbucket:

Pull Request Tools

• bitbucket_list_pull_requests - List PRs for a repository
• bitbucket_get_pull_request - Get detailed PR information
• bitbucket_get_pr_diff - Get PR changes/diff
• bitbucket_get_pr_commits - Get commits in a PR
• bitbucket_get_pr_activities - Get PR comments and activities
• bitbucket_add_pr_comment - Add a general comment
• bitbucket_add_pr_inline_comment - Add inline code comment
• bitbucket_reply_to_comment - Reply to a comment
• bitbucket_resolve_comment - Resolve a comment thread
• bitbucket_update_comment - Edit a comment
• bitbucket_approve_pr - Approve a pull request

Repository Tools

• bitbucket_list_projects - List accessible projects
• bitbucket_list_repositories - List repos in a project
• bitbucket_get_repository - Get repository details
• bitbucket_get_branches - List repository branches
• bitbucket_get_commits - Get commit history
• bitbucket_get_file_content - Get file content at ref

Code Search Tools

• bitbucket_search_code - Search code across repositories
• bitbucket_search_commits - Search commits by message

See docs/TOOLS.md for detailed tool documentation (coming soon).

Development

VSCode Setup (Recommended)

This project includes VSCode workspace settings and extension recommendations. When you open the project in VSCode, you'll be prompted to install:

• ESLint - Code linting
• Prettier - Code formatting
• Markdownlint - Markdown style checking

All formatting and linting happens automatically on save.

Development Commands

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Watch mode for development
pnpm run watch

# Run with local changes
pnpm link --global

# Code quality checks
pnpm run format:all # Format all files
pnpm run lint:all   # Lint all files (markdown + code)
pnpm run typecheck  # Type check with TypeScript
pnpm run validate   # Run all checks (format + lint + typecheck)

Git Hooks

This project uses Husky for Git hooks to maintain code quality and consistency:

Pre-commit Hook

Automatically runs before each commit:

1. Prettier - Formats all code
2. ESLint - Lints and auto-fixes issues
3. TypeScript - Type checks the code
4. Build - Ensures project compiles

This ensures all committed code meets quality standards.

Commit Message Hook

• Enforces Conventional Commits format
• Valid formats: <type>(<optional-scope>): <description>
• Allowed types: feat, fix, docs, style, refactor, test, chore, ci, build, perf, revert
• Examples:
  • feat: add user authentication
  • fix(auth): resolve login bug
  • docs: update README

Pre-push Hook

• Validates branch naming convention
• Allowed patterns:
  • main, master, develop, dev
  • feature/<description>, feat/<description>
  • bugfix/<description>, fix/<description>
  • hotfix/<description>
  • release/<version>
  • chore/<description>, docs/<description>
• Examples:
  • feature/user-authentication
  • fix/login-bug
  • release/v1.0.0

Project Structure

atlassian-bitbucket-mcp/
├── .husky/              # Git hooks
│   ├── commit-msg       # Conventional commits validation
│   ├── pre-commit       # Code quality checks
│   └── pre-push         # Branch name validation
├── docs/                # Documentation
│   ├── ARCHITECTURE.md  # System architecture and design
│   ├── CODING-STANDARDS.md  # Coding standards and best practices
│   ├── BRANCH-MANAGEMENT.md  # Branch naming and management
│   └── SECURITY.md      # Security policy
├── scripts/             # Utility scripts
│   ├── check-package-security.sh
│   ├── pre-commit.sh    # Pre-commit validation script
│   ├── pre-push.sh      # Pre-push validation script
│   ├── commit-msg.sh    # Commit message validation
│   ├── validate-branch-name.sh  # Branch name validator
│   └── setup-vscode.sh  # VSCode workspace setup
├── types/               # Shared TypeScript type definitions
│   ├── index.ts         # Type re-exports
│   ├── bitbucket.ts     # Bitbucket API types
│   ├── mcp.ts           # MCP protocol types
│   ├── config.ts        # Configuration types
│   ├── cache.ts         # Cache types
│   ├── logger.ts        # Logging types
│   └── common.ts        # Common utility types
├── src/                 # MCP server implementation
│   ├── index.ts         # Entry point
│   ├── server.ts        # MCP server setup
│   ├── config.ts        # Configuration
│   ├── cache.ts         # Caching layer
│   ├── logger.ts        # Centralized logging
│   ├── tools/           # MCP tool implementations
│   └── bitbucket/       # Bitbucket API client
├── openapi/             # OpenAPI specifications (future)
│   ├── bitbucket-cloud.yaml
│   └── bitbucket-server.yaml
├── package.json
├── tsconfig.json
└── README.md

Security

This project follows security best practices:

• All dependencies are checked against known compromised packages
• Minimal dependency footprint
• Regular security audits
• See docs/SECURITY.md for detailed security policy

Before Installing Packages

# Check if a package is safe
./scripts/check-package-security.sh <package-name>

License

This project is licensed under the GNU General Public License v3.0.

Documentation

For detailed information about this project, see:

• Architecture Documentation - System architecture, components, and design decisions
• Coding Standards - TypeScript standards, logging, and best practices
• Branch Management - Branch naming conventions and workflow
• Security Policy - Security guidelines and vulnerability reporting

Contributing

Contributions are welcome! Please ensure:

1. All new dependencies are verified against compromised package lists
2. Code follows the Coding Standards
3. Types use type (not interface) and are placed in types/ directory
4. Centralized logger is used at all critical paths
5. OpenAPI YAML files are updated alongside type changes
6. Tests are included for new features
7. Git hooks pass (branch naming, format, lint, typecheck, build)