The Atlassian Bitbucket MCP Server enables AI systems to securely interact with Bitbucket Cloud repositories, pull requests, workspaces, and code in real time.
With this server, you can:
Access and manage workspaces: List, filter, and retrieve workspace information
Explore repositories: Search, list, and get repository metadata
Manage pull requests: List, filter, create, and comment on PRs
Search and access code: Perform advanced searches, retrieve file content
Work with branches: Create branches, list them, and view diffs
Track commits: Access commit history and compare changes
Clone repositories: Download repositories locally for development
The server operates locally with your credentials (no remote token storage) and provides Markdown-formatted responses for seamless AI system integration.
Provides authentication and integration with Atlassian services, specifically focused on Bitbucket functionality using Atlassian API tokens.
Allows AI assistants to interact with Bitbucket repositories, including listing repositories, accessing pull requests, viewing commit information, and exploring workspaces.
Connect AI to Your Bitbucket Repositories
Transform how you work with Bitbucket by connecting Claude, Cursor AI, and other AI assistants directly to your repositories, pull requests, and code. Get instant insights, automate code reviews, and streamline your development workflow.
Current Version: 2.2.0
What You Can Do
Ask AI about your code: "What's the latest commit in my main repository?"
Get PR insights: "Show me all open pull requests that need review"
Search your codebase: "Find all JavaScript files that use the authentication function"
Review code changes: "Compare the differences between my feature branch and main"
Manage pull requests: "Create a PR for my new-feature branch"
Automate workflows: "Add a comment to PR #123 with the test results"
Related MCP server: GitHub MCP Tools
Perfect For
Developers who want AI assistance with code reviews and repository management
Team Leads needing quick insights into project status and pull request activity
DevOps Engineers automating repository workflows and branch management
Anyone who wants to interact with Bitbucket using natural language
Requirements
Node.js 18.0.0 or higher
Bitbucket Cloud account (not Bitbucket Server/Data Center)
Authentication credentials: Scoped API Token (recommended) or App Password (legacy)
Quick Start
Get up and running in 2 minutes:
1. Get Your Bitbucket Credentials
IMPORTANT: Bitbucket App Passwords are being deprecated and will be removed by June 2026. We recommend using Scoped API Tokens for new setups.
Option A: Scoped API Token (Recommended - Future-Proof)
Bitbucket is deprecating app passwords. Use the new scoped API tokens instead:
Go to Atlassian API Tokens
Click "Create API token with scopes"
Select "Bitbucket" as the product
Choose the appropriate scopes:
For read-only access:
repository,workspaceFor full functionality:
repository,workspace,pullrequest
Copy the generated token (starts with
ATATT)Use with your Atlassian email as the username
Option B: App Password (Legacy - Will be deprecated)
Generate a Bitbucket App Password (legacy method):
Go to Bitbucket App Passwords
Click "Create app password"
Give it a name like "AI Assistant"
Select these permissions:
Workspaces: Read
Repositories: Read (and Write if you want AI to create PRs/comments)
Pull Requests: Read (and Write for PR management)
2. Try It Instantly
Connect to AI Assistants
For Claude Desktop Users
Add this to your Claude configuration file (~/.claude/claude_desktop_config.json):
Option 1: Scoped API Token (recommended - future-proof)
Option 2: Legacy App Password (will be deprecated June 2026)
Restart Claude Desktop, and you'll see the bitbucket server in the status bar.
For Other AI Assistants
Most AI assistants support MCP. You can either:
Option 1: Use npx (recommended - always latest version):
Configure your AI assistant to run: npx -y @aashari/mcp-server-atlassian-bitbucket
Option 2: Install globally:
Then configure your AI assistant to use the MCP server with STDIO transport.
Supported AI assistants:
Claude Desktop (official support)
Cursor AI
Continue.dev
Cline
Any MCP-compatible client
Alternative: Configuration File
Create ~/.mcp/configs.json for system-wide configuration:
Option 1: Scoped API Token (recommended - future-proof)
Option 2: Legacy App Password (will be deprecated June 2026)
Alternative config keys: The system also accepts "atlassian-bitbucket", "@aashari/mcp-server-atlassian-bitbucket", or "mcp-server-atlassian-bitbucket" instead of "bitbucket".
Available Tools
This MCP server provides 6 generic tools that can access any Bitbucket API endpoint:
Tool | Description | Parameters |
| GET any Bitbucket API endpoint (read data) |
,
,
,
|
| POST to any endpoint (create resources) |
,
,
,
,
|
| PUT to any endpoint (replace resources) |
,
,
,
,
|
| PATCH any endpoint (partial updates) |
,
,
,
,
|
| DELETE any endpoint (remove resources) |
,
,
,
|
| Clone a repository locally |
,
,
|
Tool Parameters
All API tools support these common parameters:
path(required): API endpoint path starting with/(the/2.0prefix is added automatically)queryParams(optional): Key-value pairs for query parameters (e.g.,{"pagelen": "25", "page": "2"})jq(optional): JMESPath expression to filter/transform the response - highly recommended to reduce token costsoutputFormat(optional):"toon"(default, 30-60% fewer tokens) or"json"body(required for POST/PUT/PATCH): Request body as JSON object
Common API Paths
All paths automatically have /2.0 prepended. Full Bitbucket Cloud REST API 2.0 reference: https://developer.atlassian.com/cloud/bitbucket/rest/
Workspaces & Repositories:
/workspaces- List all workspaces/repositories/{workspace}- List repos in workspace/repositories/{workspace}/{repo}- Get repo details/repositories/{workspace}/{repo}/refs/branches- List branches/repositories/{workspace}/{repo}/refs/branches/{branch_name}- Get/delete branch/repositories/{workspace}/{repo}/commits- List commits/repositories/{workspace}/{repo}/commits/{commit}- Get commit details/repositories/{workspace}/{repo}/src/{commit}/{filepath}- Get file content
Pull Requests:
/repositories/{workspace}/{repo}/pullrequests- List PRs (GET) or create PR (POST)/repositories/{workspace}/{repo}/pullrequests/{id}- Get/update/delete PR/repositories/{workspace}/{repo}/pullrequests/{id}/diff- Get PR diff/repositories/{workspace}/{repo}/pullrequests/{id}/comments- List/add PR comments/repositories/{workspace}/{repo}/pullrequests/{id}/approve- Approve PR (POST) or remove approval (DELETE)/repositories/{workspace}/{repo}/pullrequests/{id}/request-changes- Request changes (POST)/repositories/{workspace}/{repo}/pullrequests/{id}/merge- Merge PR (POST)/repositories/{workspace}/{repo}/pullrequests/{id}/decline- Decline PR (POST)
Comparisons:
/repositories/{workspace}/{repo}/diff/{source}..{destination}- Compare branches/commits
Other Resources:
/repositories/{workspace}/{repo}/issues- List/manage issues/repositories/{workspace}/{repo}/downloads- List/manage downloads/repositories/{workspace}/{repo}/pipelines- Access Bitbucket Pipelines/repositories/{workspace}/{repo}/deployments- View deployments
TOON Output Format
What is TOON? Token-Oriented Object Notation is a format optimized for LLMs that reduces token consumption by 30-60% compared to JSON. It uses tabular arrays and minimal syntax while preserving all data.
Default behavior: All tools return TOON format by default. You can override this with outputFormat: "json" if needed.
Example comparison:
Learn more: https://github.com/toon-format/toon
JMESPath Filtering
All tools support optional JMESPath (jq) filtering to extract specific data and reduce token costs further:
Important: Always use jq to filter responses! Unfiltered API responses can be very large and expensive in terms of tokens.
Common JMESPath patterns:
values[*].fieldName- Extract single field from all itemsvalues[*].{key1: field1, key2: field2}- Create custom object shapevalues[0]- Get first item onlyvalues[:5]- Get first 5 itemsvalues[?state=='OPEN']- Filter by condition
Full JMESPath reference: https://jmespath.org
Real-World Examples
Explore Your Repositories
Ask your AI assistant:
"List all repositories in my main workspace"
"Show me details about the backend-api repository"
"What's the commit history for the feature-auth branch?"
"Get the content of src/config.js from the main branch"
Manage Pull Requests
Ask your AI assistant:
"Show me all open pull requests that need review"
"Get details about pull request #42 including the code changes"
"Create a pull request from feature-login to main branch"
"Add a comment to PR #15 saying the tests passed"
"Approve pull request #33"
Work with Branches and Code
Ask your AI assistant:
"Compare my feature branch with the main branch"
"List all branches in the user-service repository"
"Show me the differences between commits abc123 and def456"
Advanced Usage
Cost Optimization Tips
Always use JMESPath filtering - Extract only needed fields to minimize token usage
Use pagination wisely - Set
pagelenquery parameter to limit results (e.g.,{"pagelen": "10"})Explore schema first - Fetch one item without filters to see available fields, then filter subsequent calls
Leverage TOON format - Default TOON format saves 30-60% tokens vs JSON
Query parameters for filtering - Use Bitbucket's
qparameter for server-side filtering before results are returned
Query Parameter Examples
Working with Large Responses
When dealing with APIs that return large payloads:
Use sparse fieldsets - Add
fieldsquery parameter:{"fields": "values.name,values.slug"}Paginate results - Use
pagelenandpageparametersFilter at the source - Use Bitbucket's
qparameter for server-side filteringPost-process with JQ - Further filter the response with JMESPath
Example combining all techniques:
Best Practices for AI Interactions
Be specific with paths - Use exact workspace/repo slugs (case-sensitive)
Test with CLI first - Verify paths and authentication before using in AI context
Use descriptive JQ filters - Extract meaningful field names for better AI understanding
Enable DEBUG for troubleshooting - See exactly what's being sent to Bitbucket API
Check API limits - Bitbucket Cloud has rate limits; use filtering to reduce calls
CLI Commands
The CLI mirrors the MCP tools for direct terminal access. All commands return JSON output (not TOON - TOON is only for MCP mode).
Available Commands
CLI Options
For
-p, --path <path>(required) - API endpoint path-q, --query-params <json>(optional) - Query parameters as JSON string--jq <expression>(optional) - JMESPath filter expression
For
-p, --path <path>(required) - API endpoint path-b, --body <json>(required) - Request body as JSON string-q, --query-params <json>(optional) - Query parameters as JSON string--jq <expression>(optional) - JMESPath filter expression
For
--workspace-slug <slug>(optional) - Workspace slug (uses default if not provided)--repo-slug <slug>(required) - Repository slug--target-path <path>(required) - Absolute path to parent directory where repo will be cloned
Debugging
Enable Debug Mode
Set the DEBUG environment variable to see detailed logging:
Log files: When running in MCP mode, logs are written to ~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log
Test with HTTP Mode
For interactive debugging, run the server in HTTP mode and use the MCP Inspector:
This opens a visual interface to test tools and see request/response data.
Common Issues
Server not appearing in Claude Desktop:
Check config file syntax (valid JSON)
Restart Claude Desktop completely
Check Claude Desktop logs:
~/Library/Logs/Claude/mcp*.log(macOS)
Tools not working:
Enable DEBUG mode to see detailed errors
Test with CLI first to isolate MCP vs credentials issues
Verify API paths are correct (case-sensitive)
Troubleshooting
"Authentication failed" or "403 Forbidden"
Choose the right authentication method:
Standard Atlassian method (recommended): Use your Atlassian account email + API token (works with any Atlassian service)
Bitbucket-specific method (legacy): Use your Bitbucket username + App password (Bitbucket only)
For Scoped API Tokens (recommended):
Go to Atlassian API Tokens
Make sure your token is still active and has the right scopes
Required scopes:
repository,workspace(addpullrequestfor PR management)Token should start with
ATATT
For Bitbucket App Passwords (legacy):
Go to Bitbucket App Passwords
Make sure your app password has the right permissions
Remember: App passwords will be deprecated by June 2026
Verify your credentials:
# Test credentials with CLI export ATLASSIAN_USER_EMAIL="your.email@company.com" export ATLASSIAN_API_TOKEN="your_token" npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"Environment variable naming:
Use
ATLASSIAN_USER_EMAIL+ATLASSIAN_API_TOKENfor scoped tokensUse
ATLASSIAN_BITBUCKET_USERNAME+ATLASSIAN_BITBUCKET_APP_PASSWORDfor app passwordsDon't use
ATLASSIAN_SITE_NAME- it's not needed for Bitbucket Cloud
"Resource not found" or "404"
Check the API path:
Paths are case-sensitive
Use workspace slug (from URL), not display name
Example: If your repo URL is
https://bitbucket.org/myteam/my-repo, usemyteamandmy-repo
Verify the resource exists:
# List workspaces to find the correct slug npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
Claude Desktop Integration Issues
Restart Claude Desktop after updating the config file
Verify config file location:
macOS:
~/.claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Getting Help
If you're still having issues:
Run a simple test command to verify everything works
Check the GitHub Issues for similar problems
Create a new issue with your error message and setup details
Frequently Asked Questions
What permissions do I need?
For Scoped API Tokens (recommended):
Required scopes:
repository,workspaceAdd
pullrequestfor PR management
For Bitbucket App Passwords (legacy):
For read-only access: Workspaces: Read, Repositories: Read, Pull Requests: Read
For full functionality: Add "Write" permissions for Repositories and Pull Requests
Can I use this with private repositories?
Yes! This works with both public and private repositories. You just need the appropriate permissions through your credentials.
What AI assistants does this work with?
Any AI assistant that supports the Model Context Protocol (MCP):
Claude Desktop
Cursor AI
Continue.dev
Many others
Is my data secure?
Yes! This tool:
Runs entirely on your local machine
Uses your own Bitbucket credentials
Never sends your data to third parties
Only accesses what you give it permission to access
What's New
Version 2.2.0 (December 2024)
Modernized to MCP SDK v1.23.0 with
registerToolAPIAdded raw response logging with truncation for large API responses
Improved debugging capabilities
Version 2.1.0 (November 2024)
TOON output format - 30-60% fewer tokens than JSON
Token-efficient responses by default with JSON fallback option
Significant cost reduction for LLM interactions
Version 2.0.0 (November 2024) - Breaking Changes
Replaced 20+ specific tools with 6 generic HTTP method tools
Simplified architecture: ~14,000 fewer lines of code
Future-proof: new API endpoints work without code changes
Added optional JMESPath filtering for all responses
Migration from v1.x
Version 2.0 represents a major architectural change. If you're upgrading from v1.x:
Before (v1.x) - 20+ specific tools:
After (v2.0+) - 6 generic tools:
Migration Examples
v1.x Tool | v2.0+ Equivalent |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Key Changes
All tools now require explicit paths - more verbose but more flexible
Use JMESPath filtering - extract only what you need to reduce tokens
TOON format by default - 30-60% fewer tokens (can override with
outputFormat: "json")Direct Bitbucket API access - any API endpoint works, no code changes needed for new features
Support
Need help? Here's how to get assistance:
Check the troubleshooting section above - most common issues are covered there
Visit our GitHub repository for documentation and examples: github.com/aashari/mcp-server-atlassian-bitbucket
Report issues at GitHub Issues
Start a discussion for feature requests or general questions
Made with care for developers who want to bring AI into their Bitbucket workflow.