This MCP server connects AI assistants like Claude and Cursor to your Bitbucket repositories, allowing you to interact with your code, pull requests, and repositories using natural language.
repository, workspacerepository, workspace, pullrequestATATT)# Set credentials (choose one method)
# Method 1: Scoped API Token (recommended)
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"
# OR Method 2: Legacy App Password
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"
# List your workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
# List repositories in a workspace
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace"
Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
"env": {
"ATLASSIAN_USER_EMAIL": "[email protected]",
"ATLASSIAN_API_TOKEN": "your_scoped_api_token"
}
}
}
}
Restart Claude Desktop, and you'll see the bitbucket server in the status bar.
Most AI assistants that support MCP can use this server:
Option 1: Use npx (recommended):
Configure your AI assistant to run: npx -y @aashari/mcp-server-atlassian-bitbucket
Option 2: Install globally:
npm install -g @aashari/mcp-server-atlassian-bitbucket
Create ~/.mcp/configs.json for system-wide configuration:
{
"bitbucket": {
"environments": {
"ATLASSIAN_USER_EMAIL": "[email protected]",
"ATLASSIAN_API_TOKEN": "your_scoped_api_token",
"BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
}
}
}
This MCP server provides 6 generic tools that can access any Bitbucket API endpoint:
| Tool | Description | Parameters |
|---|---|---|
bb_get |
GET any Bitbucket API endpoint (read data) | path, queryParams?, jq?, outputFormat? |
bb_post |
POST to any endpoint (create resources) | path, body, queryParams?, jq?, outputFormat? |
bb_put |
PUT to any endpoint (replace resources) | path, body, queryParams?, jq?, outputFormat? |
bb_patch |
PATCH any endpoint (partial updates) | path, body, queryParams?, jq?, outputFormat? |
bb_delete |
DELETE any endpoint (remove resources) | path, queryParams?, jq?, outputFormat? |
bb_clone |
Clone a repository locally | workspaceSlug?, repoSlug, targetPath |
path (required): API endpoint path starting with / (the /2.0 prefix is added automatically)queryParams (optional): Query parameters as key-value pairsjq (optional): JMESPath expression to filter/transform the responseoutputFormat (optional): "toon" (default, uses 30-60% fewer tokens) or "json"body (required for POST/PUT/PATCH): Request body as JSON object# Workspaces & Repositories
/workspaces
/repositories/{workspace}
/repositories/{workspace}/{repo}
/repositories/{workspace}/{repo}/refs/branches
/repositories/{workspace}/{repo}/commits
/repositories/{workspace}/{repo}/src/{commit}/{filepath}
# Pull Requests
/repositories/{workspace}/{repo}/pullrequests
/repositories/{workspace}/{repo}/pullrequests/{id}
/repositories/{workspace}/{repo}/pullrequests/{id}/diff
/repositories/{workspace}/{repo}/pullrequests/{id}/comments
# List all repositories in a workspace
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace" \
--jq "values[].name"
# Get repository details
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace/myrepo" \
--jq "{name: name, language: language}"
# List branches
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace/myrepo/refs/branches"
# List open pull requests
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/myworkspace/myrepo/pullrequests" \
--query-params '{"state": "OPEN"}' \
--jq "values[*].{id: id, title: title}"
# Create a pull request
npx -y @aashari/mcp-server-atlassian-bitbucket post \
--path "/repositories/myworkspace/myrepo/pullrequests" \
--body '{"title": "My PR", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}'
# Add a comment to a PR
npx -y @aashari/mcp-server-atlassian-bitbucket post \
--path "/repositories/myworkspace/myrepo/pullrequests/42/comments" \
--body '{"content": {"raw": "Looks good!"}}'
pagelen query parameter to limit results# Example of optimized query
npx -y @aashari/mcp-server-atlassian-bitbucket get \
--path "/repositories/workspace/repo/pullrequests" \
--query-params '{"state": "OPEN", "pagelen": "5"}' \
--jq "values[*].{id: id, title: title}"
If you see "Authentication failed" or "403 Forbidden":
Verify your credentials match the authentication method:
ATLASSIAN_USER_EMAIL + ATLASSIAN_API_TOKENATLASSIAN_BITBUCKET_USERNAME + ATLASSIAN_BITBUCKET_APP_PASSWORDTest credentials with CLI:
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_token"
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
# For CLI testing
DEBUG=true npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
# For Claude Desktop - add to config
{
"mcpServers": {
"bitbucket": {
"env": {
"DEBUG": "true",
"ATLASSIAN_USER_EMAIL": "...",
"ATLASSIAN_API_TOKEN": "..."
}
}
}
}
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "bitbucket" '{"command":"npx","args":["-y","@aashari/mcp-server-atlassian-bitbucket"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@aashari/mcp-server-atlassian-bitbucket"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@aashari/mcp-server-atlassian-bitbucket"
]
}
}
}3. Restart Claude Desktop for the changes to take effect