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.
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"
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
Quick Start
Get up and running in 2 minutes:
1. Get Your Bitbucket Credentials
Generate a Bitbucket App Password:
- 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: Standard Atlassian credentials (recommended)
Option 2: Bitbucket-specific credentials
Restart Claude Desktop, and you'll see "🔗 bitbucket" in the status bar.
For Other AI Assistants
Most AI assistants support MCP. Install the server globally:
Then configure your AI assistant to use the MCP server with STDIO transport.
Alternative: Configuration File
Create ~/.mcp/configs.json
for system-wide configuration:
Option 1: Standard Atlassian credentials (recommended)
Option 2: Bitbucket-specific credentials
Alternative config keys: The system also accepts "atlassian-bitbucket"
, "@aashari/mcp-server-atlassian-bitbucket"
, or "mcp-server-atlassian-bitbucket"
instead of "bitbucket"
.
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"
- "Create a new branch called hotfix-login from the main branch"
- "List all branches in the user-service repository"
- "Show me the differences between commits abc123 and def456"
🔎 Search and Discovery
Ask your AI assistant:
- "Search for JavaScript files that contain 'authentication'"
- "Find all pull requests related to the login feature"
- "Search for repositories in the mobile project"
- "Show me code files that use the React framework"
Troubleshooting
"Authentication failed" or "403 Forbidden"
- Choose the right authentication method:
- Standard Atlassian method: Use your Atlassian account email + API token (works with any Atlassian service)
- Bitbucket-specific method: Use your Bitbucket username + App password (Bitbucket only)
- For Bitbucket App Passwords (if using Option 2):
- Go to Bitbucket App Passwords
- Make sure your app password has the right permissions (Workspaces: Read, Repositories: Read, Pull Requests: Read)
- For Atlassian API Tokens (if using Option 1):
- Go to Atlassian API Tokens
- Make sure your token is still active
- Verify your credentials:
"Workspace not found" or "Repository not found"
- Check your workspace slug:
- Use the exact slug from Bitbucket URL:
- If your repo URL is
https://bitbucket.org/myteam/my-repo
- Workspace slug is
myteam
- Repository slug is
my-repo
- If your repo URL is
"No default workspace configured"
Set a default workspace to avoid specifying it every time:
Claude Desktop Integration Issues
- Restart Claude Desktop after updating the config file
- Check the status bar for the "🔗 bitbucket" indicator
- Verify config file location:
- macOS:
~/.claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
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 Standard Atlassian credentials (Option 1):
- Your regular Atlassian account with access to Bitbucket
- API token with default permissions
For Bitbucket App Passwords (Option 2):
- For read-only access (viewing repos, PRs, commits):
- Workspaces: Read
- Repositories: Read
- Pull Requests: Read
- For full functionality (creating PRs, commenting):
- 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 Bitbucket App Password.
Do I need to specify workspace every time?
No! Set BITBUCKET_DEFAULT_WORKSPACE
in your environment or config file, and it will be used automatically when you don't specify one.
What AI assistants does this work with?
Any AI assistant that supports the Model Context Protocol (MCP):
- Claude Desktop (most popular)
- 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
Can I use this for multiple Bitbucket accounts?
Currently, each installation supports one set of credentials. For multiple accounts, you'd need separate configurations.
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 ❤️ for developers who want to bring AI into their Bitbucket workflow.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
An integration tool that enables AI assistants like Claude to directly access and interact with Bitbucket repositories, pull requests, and code without requiring copy/paste operations.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants like Claude to interact with GitHub repositories, issues, and pull requests.Last updated -9
- -securityFlicense-qualityA Multi-Claude Program for interacting with GitHub APIs through Claude Desktop, allowing users to search repositories, manage issues, pull requests, repository settings, workflows, and collaborators.Last updated -1
- -securityAlicense-qualityConnects Claude Desktop to GitHub repositories, enabling users to perform git operations and GitHub API interactions through natural conversation.Last updated -413MIT License
- -securityFlicense-qualityA set of tools allowing AI assistants to interact directly with GitHub, enabling automation of tasks like fetching user profiles, creating repositories, and managing pull requests.Last updated -