Bitbucket Automation via Rube MCP

Automate Bitbucket operations including repository management, pull request workflows, branch operations, issue tracking, and workspace administration through Composio's Bitbucket toolkit.

Prerequisites

• Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
• Active Bitbucket connection via RUBE_MANAGE_CONNECTIONS with toolkit bitbucket
• Always call RUBE_SEARCH_TOOLS first to get current tool schemas

Setup

Get Rube MCP: Add https://rube.app/mcp as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

• Verify Rube MCP is available by confirming RUBE_SEARCH_TOOLS responds
• Call RUBE_MANAGE_CONNECTIONS with toolkit bitbucket
• If connection is not ACTIVE, follow the returned auth link to complete Bitbucket OAuth
• Confirm connection status shows ACTIVE before running any workflows

Core Workflows

1. Manage Pull Requests

When to use: User wants to create, review, or inspect pull requests

Tool sequence:

• BITBUCKET_LIST_WORKSPACES - Discover accessible workspaces [Prerequisite]
• BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - Find the target repository [Prerequisite]
• BITBUCKET_LIST_BRANCHES - Verify source and destination branches exist [Prerequisite]
• BITBUCKET_CREATE_PULL_REQUEST - Create a new PR with title, source branch, and optional reviewers [Required]
• BITBUCKET_LIST_PULL_REQUESTS - List PRs filtered by state (OPEN, MERGED, DECLINED) [Optional]
• BITBUCKET_GET_PULL_REQUEST - Get full details of a specific PR by ID [Optional]
• BITBUCKET_GET_PULL_REQUEST_DIFF - Fetch unified diff for code review [Optional]
• BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - Get changed files with lines added/removed [Optional]

Key parameters:

• workspace: Workspace slug or UUID (required for all operations)
• repo_slug: URL-friendly repository name
• source_branch: Branch with changes to merge
• destination_branch: Target branch (defaults to repo main branch if omitted)
• reviewers: List of objects with uuid field for reviewer assignment
• state: Filter for LIST_PULL_REQUESTS - OPEN, MERGED, or DECLINED
• max_chars: Truncation limit for GET_PULL_REQUEST_DIFF to handle large diffs

Pitfalls:

• reviewers expects an array of objects with uuid key, NOT usernames: [{"uuid": "{...}"}]
• UUID format must include curly braces: {123e4567-e89b-12d3-a456-426614174000}
• destination_branch defaults to the repo's main branch if omitted, which may not be main
• pull_request_id is an integer for GET/DIFF operations but comes back as part of PR listing
• Large diffs can overwhelm context; always set max_chars (e.g., 50000) on GET_PULL_REQUEST_DIFF

2. Manage Repositories and Workspaces

When to use: User wants to list, create, or delete repositories or explore workspaces

Tool sequence:

• BITBUCKET_LIST_WORKSPACES - List all accessible workspaces [Required]
• BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE - List repos with optional BBQL filtering [Required]
• BITBUCKET_CREATE_REPOSITORY - Create a new repo with language, privacy, and project settings [Optional]
• BITBUCKET_DELETE_REPOSITORY - Permanently delete a repository (irreversible) [Optional]
• BITBUCKET_LIST_WORKSPACE_MEMBERS - List members for reviewer assignment or access checks [Optional]

Key parameters:

• workspace: Workspace slug (find via LIST_WORKSPACES)
• repo_slug: URL-friendly name for create/delete
• q: BBQL query filter (e.g., name~"api", project.key="PROJ", is_private=true)
• role: Filter repos by user role: member, contributor, admin, owner
• sort: Sort field with optional - prefix for descending (e.g., -updated_on)
• is_private: Boolean for repository visibility (defaults to true)
• project_key: Bitbucket project key; omit to use workspace's oldest project

Pitfalls:

• BITBUCKET_DELETE_REPOSITORY is irreversible and does not affect forks
• BBQL string values MUST be enclosed in double quotes: name~"my-repo" not name~my-repo
• repository is NOT a valid BBQL field; use name instead
• Default pagination is 10 results; set pagelen explicitly for complete listings
• CREATE_REPOSITORY defaults to private; set is_private: false for public repos

3. Manage Issues

When to use: User wants to create, update, list, or comment on repository issues

Tool sequence:

• BITBUCKET_LIST_ISSUES - List issues with optional filters for state, priority, kind, assignee [Required]
• BITBUCKET_CREATE_ISSUE - Create a new issue with title, content, priority, and kind [Required]
• BITBUCKET_UPDATE_ISSUE - Modify issue attributes (state, priority, assignee, etc.) [Optional]
• BITBUCKET_CREATE_ISSUE_COMMENT - Add a markdown comment to an existing issue [Optional]
• BITBUCKET_DELETE_ISSUE - Permanently delete an issue [Optional]

Key parameters:

• issue_id: String identifier for the issue
• title, content: Required for creation
• kind: bug, enhancement, proposal, or task
• priority: trivial, minor, major, critical, or blocker
• state: new, open, resolved, on hold, invalid, duplicate, wontfix, closed
• assignee: Bitbucket username for CREATE; assignee_account_id (UUID) for UPDATE
• due_on: ISO 8601 format date string

Pitfalls:

• Issue tracker must be enabled on the repository (has_issues: true) or API calls will fail
• CREATE_ISSUE uses assignee (username string), but UPDATE_ISSUE uses assignee_account_id (UUID) -- they are different fields
• DELETE_ISSUE is permanent with no undo
• state values include spaces: "on hold" not "on_hold"
• Filtering by assignee in LIST_ISSUES uses account ID, not username; use "null" string for unassigned

4. Manage Branches

When to use: User wants to create branches or explore branch structure

Tool sequence:

• BITBUCKET_LIST_BRANCHES - List branches with optional BBQL filter and sorting [Required]
• BITBUCKET_CREATE_BRANCH - Create a new branch from a specific commit hash [Required]

Key parameters:

• name: Branch name without refs/heads/ prefix (e.g., feature/new-login)
• target_hash: Full SHA1 commit hash to branch from (must exist in repo)
• q: BBQL filter (e.g., name~"feature/", name="main")
• sort: Sort by name or -target.date (descending commit date)
• pagelen: 1-100 results per page (default is 10)

Pitfalls:

• CREATE_BRANCH requires a full commit hash, NOT a branch name as target_hash
• Do NOT include refs/heads/ prefix in branch names
• Branch names must follow Bitbucket naming conventions (alphanumeric, /, ., _, -)
• BBQL string values need double quotes: name~"feature/" not name~feature/

5. Review Pull Requests with Comments

When to use: User wants to add review comments to pull requests, including inline code comments

Tool sequence:

• BITBUCKET_GET_PULL_REQUEST - Get PR details and verify it exists [Prerequisite]
• BITBUCKET_GET_PULL_REQUEST_DIFF - Review the actual code changes [Prerequisite]
• BITBUCKET_GET_PULL_REQUEST_DIFFSTAT - Get list of changed files [Optional]
• BITBUCKET_CREATE_PULL_REQUEST_COMMENT - Post review comments [Required]

Key parameters:

• pull_request_id: String ID of the PR
• content_raw: Markdown-formatted comment text
• content_markup: Defaults to markdown; also supports plaintext
• inline: Object with path, from, to for inline code comments
• parent_comment_id: Integer ID for threaded replies to existing comments

Pitfalls:

• pull_request_id is a string in CREATE_PULL_REQUEST_COMMENT but an integer in GET_PULL_REQUEST
• Inline comments require inline.path at minimum; from/to are optional line numbers
• parent_comment_id creates a threaded reply; omit for top-level comments
• Line numbers in inline comments reference the diff, not the source file

Common Patterns

ID Resolution

Always resolve human-readable names to IDs before operations:

• Workspace: BITBUCKET_LIST_WORKSPACES to get workspace slugs
• Repository: BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE with q filter to find repo slugs
• Branch: BITBUCKET_LIST_BRANCHES to verify branch existence before PR creation
• Members: BITBUCKET_LIST_WORKSPACE_MEMBERS to get UUIDs for reviewer assignment

Pagination

Bitbucket uses page-based pagination (not cursor-based):

• Use page (starts at 1) and pagelen (items per page) parameters
• Default page size is typically 10; set pagelen explicitly (max 50 for PRs, 100 for others)
• Check response for next URL or total count to determine if more pages exist
• Always iterate through all pages for complete results

BBQL Filtering

Bitbucket Query Language is available on list endpoints:

• String values MUST use double quotes: name~"pattern"
• Operators: = (exact), ~ (contains), != (not equal), >, >=, <, <=
• Combine with AND / OR: name~"api" AND is_private=true

Known Pitfalls

ID Formats

• Workspace: slug string (e.g., my-workspace) or UUID in braces ({uuid})
• Reviewer UUIDs must include curly braces: {123e4567-e89b-12d3-a456-426614174000}
• Issue IDs are strings; PR IDs are integers in some tools, strings in others
• Commit hashes must be full SHA1 (40 characters)

Parameter Quirks

• assignee vs assignee_account_id: CREATE_ISSUE uses username, UPDATE_ISSUE uses UUID
• state values for issues include spaces: "on hold", not "on_hold"
• destination_branch omission defaults to repo main branch, not main literally
• BBQL repository is not a valid field -- use name

Rate Limits

• Bitbucket Cloud API has rate limits; large batch operations should include delays
• Paginated requests count against rate limits; minimize unnecessary page fetches

Destructive Operations

• BITBUCKET_DELETE_REPOSITORY is irreversible and does not remove forks
• BITBUCKET_DELETE_ISSUE is permanent with no recovery option
• Always confirm with the user before executing delete operations

Quick Reference

Task	Tool Slug	Key Params
List workspaces	BITBUCKET_LIST_WORKSPACES	q, sort
List repos	BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACE	workspace, q, role
Create repo	BITBUCKET_CREATE_REPOSITORY	workspace, repo_slug, is_private
Delete repo	BITBUCKET_DELETE_REPOSITORY	workspace, repo_slug
List branches	BITBUCKET_LIST_BRANCHES	workspace, repo_slug, q
Create branch	BITBUCKET_CREATE_BRANCH	workspace, repo_slug, name, target_hash
List PRs	BITBUCKET_LIST_PULL_REQUESTS	workspace, repo_slug, state
Create PR	BITBUCKET_CREATE_PULL_REQUEST	workspace, repo_slug, title, source_branch
Get PR details	BITBUCKET_GET_PULL_REQUEST	workspace, repo_slug, pull_request_id
Get PR diff	BITBUCKET_GET_PULL_REQUEST_DIFF	workspace, repo_slug, pull_request_id, max_chars
Get PR diffstat	BITBUCKET_GET_PULL_REQUEST_DIFFSTAT	workspace, repo_slug, pull_request_id
Comment on PR	BITBUCKET_CREATE_PULL_REQUEST_COMMENT	workspace, repo_slug, pull_request_id, content_raw
List issues	BITBUCKET_LIST_ISSUES	workspace, repo_slug, state, priority
Create issue	BITBUCKET_CREATE_ISSUE	workspace, repo_slug, title, content
Update issue	BITBUCKET_UPDATE_ISSUE	workspace, repo_slug, issue_id
Comment on issue	BITBUCKET_CREATE_ISSUE_COMMENT	workspace, repo_slug, issue_id, content
Delete issue	BITBUCKET_DELETE_ISSUE	workspace, repo_slug, issue_id
List members	BITBUCKET_LIST_WORKSPACE_MEMBERS	workspace