Bitbucket MCP
Model Context Protocol (MCP) server for Bitbucket Cloud and Server API integration. This package enables AI assistants to interact with Bitbucket repositories, pull requests, and other features through the MCP protocol.
Features
- Bitbucket Cloud API Integration: Access the full Bitbucket Cloud REST API
- Bitbucket Server Support: Compatible with Bitbucket Server instances
- Repository Management: List, view, and manage repositories
- Pull Request Operations: Create, view, merge, and comment on PRs
- Permission Management: Query and manage repository permissions
- Webhook Management: List and manage webhooks
Installation
npm install -g bitbucket-mcp
npx bitbucket-mcp
Quick Start
- Set up your environment variables:
export BITBUCKET_URL="https://your-bitbucket-server-url"
export BITBUCKET_CLOUD_URL="https://api.bitbucket.org/2.0"
export BITBUCKET_TOKEN="your_access_token"
export BITBUCKET_USERNAME="your_username"
export BITBUCKET_APP_PASSWORD="your_app_password"
export BITBUCKET_DEFAULT_PROJECT="your_default_project"
npx bitbucket-mcp
Supported API Operations
Bitbucket Cloud Repository API
list_public_repositories
- List all public repositories
list_workspace_repositories
- List repositories in a workspace
get_repository
- Get a specific repository
list_repository_forks
- List forks of a repository
list_repository_webhooks
- List webhooks for a repository
get_repository_webhook
- Get a specific webhook
get_repository_settings_inheritance
- Get repository settings inheritance
list_repository_group_permissions
- List group permissions
get_repository_group_permission
- Get specific group permission
list_repository_user_permissions
- List user permissions
get_repository_user_permission
- Get specific user permission
list_repository_watchers
- List repository watchers
list_user_repository_permissions
- List permissions for the current user
Bitbucket Server Pull Request API
create_pull_request
- Create a new pull request
get_pull_request
- Get pull request details
merge_pull_request
- Merge a pull request
decline_pull_request
- Decline a pull request
add_comment
- Add a comment to a pull request
get_diff
- Get pull request diff
get_reviews
- Get pull request reviews
Integration with AI Assistants
This MCP server is designed to be used with AI assistants that support the Model Context Protocol:
Using with Claude
- Install the Claude desktop app
- Add this MCP server to Claude:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["-y", "bitbucket-mcp"],
"env": {
"BITBUCKET_URL": "https://your-bitbucket-server.com",
"BITBUCKET_CLOUD_URL": "https://api.bitbucket.org/2.0",
"BITBUCKET_TOKEN": "your-access-token"
}
}
}
}
Using with other MCP clients
Any client that supports the MCP protocol can communicate with this server over standard input/output.
API Examples
List repositories in a workspace
{
"jsonrpc": "2.0",
"id": 1,
"method": "mcp.call_tool",
"params": {
"name": "list_workspace_repositories",
"arguments": {
"workspace": "your_workspace"
}
}
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{ \"values\": [...], \"pagelen\": 10, ... }"
}
]
}
}
Create a pull request
{
"jsonrpc": "2.0",
"id": 2,
"method": "mcp.call_tool",
"params": {
"name": "create_pull_request",
"arguments": {
"project": "PROJECT",
"repository": "repo-name",
"title": "Feature: Add new functionality",
"description": "This PR adds the new feature X",
"sourceBranch": "feature/new-feature",
"targetBranch": "main"
}
}
}
Development
git clone https://github.com/yourusername/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
npm start
Logging
The server logs all operations to bitbucket.log
using Winston for debugging and monitoring purposes.
License
MIT