Atlassian Bitbucket MCP Server

List Bitbucket workspaces available to your account.

PURPOSE: Discovers workspaces you have access to with their slugs, names, and permission levels to help navigate Bitbucket's organization structure.

WHEN TO USE:

• When you need to discover what workspaces exist in your Bitbucket account
• When you want to find the slugs needed for other Bitbucket operations
• When you need to check what workspaces you have access to and their permission levels
• Before accessing repositories or pull requests that require workspace information
• When you're unfamiliar with the workspace organization structure

WHEN NOT TO USE:

• When you already know the workspace slug (use get-workspace or list-repositories instead)
• When you need detailed workspace information (use get-workspace instead)
• When you need to find specific repositories (use list-repositories after identifying the workspace)

RETURNS: Formatted list of workspaces with slugs, names, and permission information, plus pagination details if available.

EXAMPLES:

• List all workspaces: {}
• With sorting: {sort: "name"}
• With pagination: {limit: 10, cursor: "next-page-token"}

ERRORS:

• Authentication failures: Check your Bitbucket credentials
• No workspaces found: You might not have access to any workspaces
• Rate limiting: Use pagination and reduce query frequency

Get detailed information about a specific Bitbucket workspace by slug.

PURPOSE: Retrieves comprehensive workspace metadata including projects, permissions, and configuration.

WHEN TO USE:

• When you need detailed information about a specific workspace
• When you need to check workspace permissions or membership
• When you need to verify workspace settings or configuration
• After using list-workspaces to identify the relevant workspace
• Before performing operations that require detailed workspace context

WHEN NOT TO USE:

• When you don't know which workspace to look for (use list-workspaces first)
• When you just need basic workspace information (slug, name)
• When you're only interested in repositories (use list-repositories directly)

RETURNS: Detailed workspace information including slug, name, type, description, projects, and permission levels.

EXAMPLES:

• Get workspace: {workspace: "myteam"}

ERRORS:

• Workspace not found: Verify the workspace slug is correct
• Permission errors: Ensure you have access to the requested workspace
• Rate limiting: Cache workspace information when possible

List Bitbucket repositories within a specific workspace.

PURPOSE: Discovers repositories in a workspace with their slugs, names, and URLs to help navigate code resources.

WHEN TO USE:

• When you need to find repositories within a specific workspace
• When you need repository slugs for other Bitbucket operations
• When you want to explore available repositories before accessing specific content
• When you need to check repository visibility and access levels
• When looking for repositories with specific characteristics (language, size, etc.)

WHEN NOT TO USE:

• When you don't know which workspace to look for repos in (use list-workspaces first)
• When you already know the repository slug (use get-repository instead)
• When you need detailed repository information (use get-repository instead)
• When you need to access pull requests or branches (use dedicated tools after identifying the repo)

RETURNS: Formatted list of repositories with slugs, names, descriptions, URLs, and metadata, plus pagination info.

EXAMPLES:

• List all repos in workspace: {workspace: "myteam"}
• With sorting: {workspace: "myteam", sort: "name"}
• With filtering: {workspace: "myteam", query: "api"}
• With pagination: {workspace: "myteam", limit: 10, cursor: "next-page-token"}

ERRORS:

• Workspace not found: Verify the workspace slug is correct
• Authentication failures: Check your Bitbucket credentials
• Permission errors: Ensure you have access to the requested workspace
• Rate limiting: Use pagination and reduce query frequency

Get detailed information about a specific Bitbucket repository.

PURPOSE: Retrieves comprehensive repository metadata including branches, settings, permissions, and more.

WHEN TO USE:

• When you need detailed information about a specific repository
• When you need repository URLs, clone links, or other reference information
• When you need to check repository settings or permissions
• After using list-repositories to identify the relevant repository
• Before performing operations that require repository context (PRs, branches)

WHEN NOT TO USE:

• When you don't know which repository to look for (use list-repositories first)
• When you just need basic repository information
• When you're looking for pull request details (use list-pullrequests instead)
• When you need content from multiple repositories (use list-repositories instead)

RETURNS: Detailed repository information including slug, name, description, URLs, branch information, and settings.

EXAMPLES:

• Get repository: {workspace: "myteam", repoSlug: "project-api"}

ERRORS:

• Repository not found: Verify workspace and repository slugs
• Permission errors: Ensure you have access to the requested repository
• Rate limiting: Cache repository information when possible

List Bitbucket pull requests with optional filtering capabilities.

PURPOSE: Allows you to find and browse pull requests across repositories with filtering options.

WHEN TO USE:

• When you need to find pull requests within a specific repository
• When you want to check PR status (open, merged, declined, etc.)
• When you need to track code review activity and progress
• When you need PR IDs for other Bitbucket operations
• When monitoring contributions from specific authors

WHEN NOT TO USE:

• When you don't know which repository to look in (use list-repositories first)
• When you already know the PR ID (use get-pull-request instead)
• When you need detailed PR content or comments (use get-pull-request instead)
• When you need to browse repositories rather than PRs (use list-repositories)

RETURNS: Formatted list of pull requests with IDs, titles, states, authors, branch information, and URLs, plus pagination info.

EXAMPLES:

• List all PRs in a repo: {workspace: "myteam", repoSlug: "project-api"}
• Filter by state: {workspace: "myteam", repoSlug: "project-api", state: "OPEN"}
• With pagination: {workspace: "myteam", repoSlug: "project-api", limit: 10, cursor: "next-page-token"}

ERRORS:

• Repository not found: Verify workspace and repository slugs
• Authentication failures: Check your Bitbucket credentials
• Permission errors: Ensure you have access to the requested repository
• Rate limiting: Use pagination and reduce query frequency

Get detailed information about a specific Bitbucket pull request.

PURPOSE: Retrieves comprehensive PR data including description, comments, diff stats, reviewers, and branch information.

WHEN TO USE:

• When you need the full description and context of a specific PR
• When you need to see comments, reviews, or approvals
• When you need details about the source and destination branches
• When you need diff statistics or changed files information
• After using list-pull-requests to identify the relevant PR ID

WHEN NOT TO USE:

• When you don't know which PR to look for (use list-pull-requests first)
• When you need to browse multiple PRs (use list-pull-requests instead)
• When you only need basic PR information without comments or details
• When you need repository information rather than PR details (use get-repository)

RETURNS: Detailed PR information including title, description, status, author, reviewers, branches, comments, and related timestamps.

EXAMPLES:

• Get PR details: {workspace: "myteam", repoSlug: "project-api", id: 42}

ERRORS:

• PR not found: Verify workspace, repository slugs, and PR ID
• Permission errors: Ensure you have access to the requested PR
• Rate limiting: Cache PR information when possible for frequently referenced PRs