Bitbucket MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating with Bitbucket Cloud API. This server provides AI systems with seamless access to Bitbucket repositories, pull requests, issues, branches, commits, and more.

Features

Repository Management

• List repositories in workspaces
• Get detailed repository information
• Create new repositories
• Search repositories
• Update repository settings
• Delete repositories

Branch Management

• List branches in repositories
• Get branch details
• Create new branches
• Delete branches

Commit Management

• List commits in repositories
• Get detailed commit information
• Filter commits by branch

File Management

• Read file contents
• List directory contents
• Update files
• Delete files

Pull Request Management

• List pull requests
• Get pull request details
• Create new pull requests
• Update pull requests
• Merge pull requests
• Decline pull requests
• Manage pull request comments

Issue Management

• List issues in repositories
• Get issue details
• Create new issues
• Update issues
• Manage issue comments

User and Workspace Management

• Get current user information
• List accessible workspaces
• Get workspace details

Search and Utility

• Search code across repositories
• Get repository statistics
• Manage webhooks
• Fork repositories

Installation

1. Clone this repository:

git clone <repository-url>
cd bitbucket-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

1. Copy the example environment file:

cp env.example .env

2. Configure your Bitbucket credentials in .env. Choose one of the authentication methods below:

Authentication Methods

Option 1: OAuth 2.0 (Recommended for Production)

OAuth 2.0 provides the most secure and flexible authentication method.

1. Create an OAuth Consumer:

   • Go to your Bitbucket workspace settings
   • Navigate to "OAuth consumers" under "Access management"
   • Create a new consumer with appropriate scopes
   • See OAuth Setup Guide for detailed instructions

2. Configure OAuth in .env:

# OAuth 2.0 Configuration
BITBUCKET_CLIENT_ID=your-oauth-client-id
BITBUCKET_CLIENT_SECRET=your-oauth-client-secret
BITBUCKET_REDIRECT_URI=http://localhost:3000/oauth/callback
BITBUCKET_SCOPES=repository:read,repository:write,pullrequest:read,pullrequest:write,issue:read,issue:write,account:read

# Optional: Direct access token (if you already have one)
BITBUCKET_ACCESS_TOKEN=your-oauth-access-token
BITBUCKET_REFRESH_TOKEN=your-oauth-refresh-token

Option 2: App Password (Simple Setup)

1. Go to your Bitbucket account settings

2. Navigate to "App passwords" under "Access management"

3. Create a new app password with the required scopes:

   • Repositories: Read, Write
   • Pull requests: Read, Write
   • Issues: Read, Write
   • Account: Read

4. Configure App Password in .env:

# Basic Authentication
BITBUCKET_USERNAME=your-username
BITBUCKET_APP_PASSWORD=your-app-password
# OR use API token instead of app password
BITBUCKET_API_TOKEN=your-api-token

Option 3: API Token

1. Go to your Bitbucket account settings
2. Navigate to "Personal access tokens"
3. Create a new token with appropriate permissions

Usage

Running the Server

# Development mode
npm run dev

# Production mode
npm start

MCP Client Configuration

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-mcp-server/dist/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Available Tools

User and Workspace Management

• get_current_user - Get current user information
• get_workspace - Get workspace details
• get_workspaces - List all accessible workspaces

Repository Management

• get_repositories - List repositories in a workspace
• get_repository - Get repository details
• create_repository - Create a new repository
• search_repositories - Search repositories by query

Branch Management

• get_branches - List branches in a repository
• get_branch - Get branch details
• create_branch - Create a new branch

Commit Management

• get_commits - List commits in a repository
• get_commit - Get commit details

File Management

• get_file_content - Read file contents
• get_directory_contents - List directory contents

Pull Request Management

• get_pull_requests - List pull requests
• get_pull_request - Get pull request details
• create_pull_request - Create a new pull request
• merge_pull_request - Merge a pull request

Issue Management

• get_issues - List issues in a repository
• get_issue - Get issue details
• create_issue - Create a new issue

Search and Utility

• search_code - Search code across repositories

OAuth 2.0 Management

• generate_oauth_url - Generate OAuth authorization URL
• exchange_oauth_code - Exchange authorization code for access token
• refresh_oauth_token - Refresh OAuth access token
• validate_oauth_token - Validate OAuth access token
• revoke_oauth_token - Revoke OAuth access token
• get_oauth_user_info - Get user information using OAuth token

API Reference

The server implements the Bitbucket Cloud REST API v2. For detailed information about the API endpoints and data structures, refer to the official Bitbucket API documentation.

Error Handling

The server includes comprehensive error handling for:

• Authentication failures
• Network connectivity issues
• API rate limiting
• Invalid parameters
• Resource not found errors

All errors are returned with descriptive messages to help with debugging.

Development

Project Structure

src/
├── index.ts              # Main MCP server implementation
├── bitbucket-client.ts   # Bitbucket API client
└── types.ts              # TypeScript type definitions

Building

npm run build

Testing

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the Bitbucket API documentation
2. Review the error messages in the server logs
3. Open an issue in this repository

Changelog

v1.0.0

• Initial release
• Complete Bitbucket Cloud API integration
• Support for repositories, branches, commits, pull requests, issues
• User and workspace management
• Search functionality