MCP Server for Bitbucket
The MCP for Bitbucket Data Center (BBDC) plugin is a server that allows agents to interact with BBDC using the model context protocol. A set of tools is available to the agents as advertised by the server. By default these capabilities include:
Projects and repositories: list, search, create, and update projects and repositories; fork a repository; list forks.
Branches and tags: list, create, and delete branches and tags; get or set the default branch.
Commits and files: browse commit history, read file contents at a commit, and read or add commit comments.
Pull requests: create, update, merge, decline, reopen, approve, and unapprove pull requests; manage participants and reviewers; read and post comments; check merge eligibility.
File edits: commit a file change directly through edit_file.
My work: list pull requests assigned to or authored by the current user, and check the inbox count.
How does the MCP server work?
The MCP server has a whitelist of Bitbucket REST endpoints that are used to determine available tooling for agents. The whitelist can be configured to increase or reduce your server's REST endpoint coverage.
The whitelist sets the maximum set of tools the server can expose. Each caller sees only the tools its access token permits. A tool stays out of that caller's list when its required permission is outside the token's scope, even if the whitelist includes it.
Configuring the whitelist
The server ships with a default whitelist that covers the range of capabilities mentioned above. The whitelist can be altered by placing a file named mcp-tools.json in BITBUCKET_HOME/shared/. The whitelist matches against the full suite of Bitbucket DC REST endpoints and will include them as available tools if the method & path match an existing REST endpoint.
On plugin restart, the new whitelist will be picked up and delivered to users.
Example whitelist configuration
[
{
"method": "GET",
"path": "/rest/api/latest/projects",
"name": "list_projects",
"description": "List projects the user can access",
"permission": "PROJECT_READ"
},
{
"method": "GET",
"path": "/rest/api/latest/projects/{projectKey}",
"name": "get_project",
"description": "Get a project by key"
}
In this case, the default mcp-tools.json will be ignored and instead agents will receive a tool list of get_project and list_projects as their only available MCP tools.
What the fields denote
- Method: The endpoint method as defined in the REST docs (GET, PUT, DELETE, etc..)
- Path: The endpoint path. E.g.
/rest/api/latest/projects/{projectKey}. As defined in the REST docs and including all path params. Name: The name of the tool that will be exposed to MCP clients.
- Description: The description of the tool that is exposed to MCP clients. If omitted will default to the REST docs description.
- Permission: The permission to filter on. This tool wont be shown to clients who's token dont meet the minimum permission requirement. If omitted the tool will be shown to all clients. Available permissions are:
REPO_READREPO_CREATEREPO_ADMINPROJECT_READPROJECT_CREATEPROJECT_ADMIN
Bitbucket instance Recommendations
If your instance starts to experience heightened load due to the increased requests from MCP clients. Then we strongly recommend you enable rate limiting for BBDC.