Bitbucket Data Center

Bitbucket Data Center is the self-hosted, on-premises version of Bitbucket for enterprise teams who need full control over their Git repositories, code review workflows, and pull request processes. It differs from Bitbucket Cloud in that it runs on your own infrastructure and uses a project-based repository hierarchy instead of workspaces.

Authentication Types

Bitbucket Data Center supports 3 authentication methods:

• OAuth 2.0 - Use OAuth 2.0 with your self-hosted Bitbucket Data Center instance (requires v7.21 or later).

  • Pros: Secure, per-user tracking, production-ready, no credentials stored in MCP-S
  • Cons: Requires OAuth application configuration on Bitbucket Data Center

• API Key - Use a Personal Access Token for authentication.

  • Pros: Simple setup
  • Cons: Single credential for all users

• API Key Per User - Each user provides their own Personal Access Token.

  • Pros: Per-user tracking, audit trail
  • Cons: Each user must generate their own token

General Settings

Before using the connector, you need to configure:

• Bitbucket Instance URL - Your Bitbucket Data Center base URL (e.g., https://bitbucket.yourcompany.com). Do not include a trailing slash or any path.

Setting up OAuth 2.0

OAuth 2.0 is available for self-hosted Bitbucket Data Center instances running version 7.21 or later.

Requirements:

• Bitbucket Data Center v7.21 or later
• HTTPS enabled on your Bitbucket instance (required for production)
• Administrator access to Bitbucket Data Center

Setup Steps:

1. Log in to your Bitbucket Data Center instance as an administrator

2. Navigate to Administration → Application Links

3. Click Create link

4. Select External application and then Incoming

5. Choose OAuth 2.0 as the authentication method

6. Configure the OAuth application:

   • Name: Enter a descriptive name (e.g., "MCP-S Integration")
   • Redirect URL: Copy this from MCP-S and paste it here
   • Scopes: Enable the required scopes

7. Click Save and copy the Client ID and Client Secret

8. In MCP-S:

   • Paste the Client ID and Client Secret
   • Enter your Bitbucket Data Center instance URL in Bitbucket Instance URL (e.g., https://bitbucket.yourcompany.com)

9. Click Save Changes and authorize

Additional Information:

• For detailed configuration steps, see Atlassian's official OAuth 2.0 documentation
• Access tokens expire after 2 hours by default and are automatically refreshed

Generating a Personal Access Token

1. Log in to your Bitbucket Data Center instance

2. Click your profile avatar in the top-right corner

3. Go to Manage account

4. In the left sidebar, click Personal Access Tokens

5. Click Create a token

6. Enter a Token name and select the permissions you need:

   • Repositories (Read) — required for all read operations
   • Repositories (Write) — required for creating branches and pull requests
   • Projects (Read) — required for listing projects

7. Optionally set an expiry date

8. Click Create

9. Copy the token immediately (it won't be shown again)

10. Paste the token into MCP-S

11. Enter your Bitbucket Instance URL in General Settings

Available Scopes

Bitbucket Data Center uses the following OAuth 2.0 scopes:

Scope	Description
PUBLIC_REPOS	Access public repositories
REPO_READ	Read access to repositories, pull requests, branches
REPO_WRITE	Write access (includes REPO_READ)
REPO_ADMIN	Administrative access to repositories
PROJECT_ADMIN	Administrative access to projects

Recommended Scopes:

• For most integrations: REPO_READ
• For creating pull requests and branches: REPO_READ and REPO_WRITE
• For administrative operations: Add REPO_ADMIN or PROJECT_ADMIN

Available Tools

The Bitbucket Data Center connector provides the following tools:

Projects

• List Projects - List all accessible projects in Bitbucket Data Center
• Get Project - Get details of a specific project by its key

Repositories

• List Repositories - List repositories within a specific project
• Get Repository - Get details of a specific repository
• Search Repositories - Search for repositories by name across all projects

Pull Requests

• List Pull Requests - List pull requests in a repository, filterable by state
• Get Pull Request - Get details of a specific pull request
• Create Pull Request - Create a new pull request with reviewers
• Update Pull Request - Update a pull request's title, description, or reviewers
• Merge Pull Request - Merge a pull request with an optional strategy
• Approve Pull Request - Approve a pull request as the authenticated user
• Decline Pull Request - Decline a pull request
• Get Pull Request Comments - List all comments on a pull request
• Add Pull Request Comment - Add a general or inline code comment to a pull request
• Get Pull Request Diff - Get the unified diff for a pull request
• Get Pull Request Commits - List commits included in a pull request

Branches

• List Branches - List branches in a repository with optional filtering
• Create Branch - Create a new branch from a branch name, tag, or commit hash

Commits & Files

• List Commits - List commits in a repository or on a specific branch
• Get Commit - Get details of a specific commit
• Get File Content - Get the raw content of a file at a specific branch or commit
• List Files - List files and directories at a given path in the repository

Troubleshooting

OAuth 2.0 Issues

Problem: "OAuth application not found" error

Solution:

• Verify the Client ID and Client Secret are correct
• Ensure the OAuth application is configured as "Incoming" in Application Links
• Check that the Redirect URL matches exactly

Problem: "Invalid redirect URI" error

Solution:

• Copy the exact Redirect URL from MCP-S (don't type it manually)
• Ensure there are no extra spaces or characters

Personal Access Token Issues

Problem: "401 Unauthorized" with Personal Access Token

Solution:

• Verify the token was copied correctly (no extra whitespace)
• Check if the token has expired
• Ensure your Bitbucket Instance URL is correct and does not have a trailing slash
• Verify the token belongs to a user with appropriate repository permissions

Connection Issues

Problem: "Cannot connect to Bitbucket instance"

Solution:

• Verify the Bitbucket Instance URL is correct (e.g., https://bitbucket.yourcompany.com)
• Do not include /rest or any path suffix in the URL
• Ensure HTTPS is used (required for OAuth 2.0)
• Check that the instance is accessible from MCP-S (no firewall blocking)

API Issues

Problem: "Permission denied" errors on repository operations

Solution:

• Verify the authenticated user has appropriate project and repository permissions
• Check project permissions in Project Settings → Permissions
• Some operations (like merge) require a minimum role of Write

Problem: Version conflict errors on merge, update, or decline

Solution:

• These operations require the current version of the pull request
• Use the Get Pull Request tool first to retrieve the current version number, then pass it to the operation

API Differences from Bitbucket Cloud

If you're migrating from Bitbucket Cloud, note these key differences:

Aspect	Bitbucket Cloud	Bitbucket Data Center
API Base Path	https://api.bitbucket.org/2.0	{instanceUrl}/rest/api/1.0
URL Structure	/repositories/{workspace}/{repo_slug}	/projects/{projectKey}/repos/{repoSlug}
Hierarchy	Workspaces → Repositories	Projects → Repositories
Authentication	OAuth via bitbucket.org, username:app_password	OAuth via {instanceUrl}, Personal Access Tokens
Pagination	page + pagelen	start (0-based) + limit
Pipelines	Supported (Cloud-only feature)	Not available (use Bamboo or Jenkins instead)
PR Version	Not required for mutations	Required (version field) for merge/update/decline

Best Practices

1. Use OAuth 2.0 for production - It's more secure and provides per-user tracking
2. Always fetch before mutating - Retrieve a pull request with Get Pull Request before merging, updating, or declining it to get the current version for optimistic locking
3. Use Search Repositories for discovery - When you don't know the project key, Search Repositories lets you find repos across all projects
4. Handle pagination - Responses include isLastPage and nextPageStart fields; use the start parameter to page through results
5. Set expiry dates on PATs - Personal Access Tokens should have an expiry date set for security

Additional Resources

• Bitbucket Data Center REST API Documentation
• Bitbucket Data Center OAuth 2.0 Provider API
• Personal Access Tokens in Bitbucket
• Bitbucket Data Center Documentation