# Bitbucket MCP Server
[](LICENSE)
[](https://nodejs.org)
[](https://github.com/modelcontextprotocol/sdk)
A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with Bitbucket repositories, manage pull requests, analyze code, and perform various repository operations.
## 🌟 Features
### Repository Management
- List workspaces and repositories
- Get detailed repository information
- Search code across repositories
- Access file contents
### Branch Operations
- List and get branch details
- Compare branches
- View branch history
### Pull Request Management
- List, create, and manage pull requests
- Approve and merge pull requests
- Add comments and reviews
- Filter by status (OPEN, MERGED, DECLINED)
### Commit Operations
- List and analyze commits
- Get commit details and diffs
- Filter commits by branch
## 🚀 Quick Start
### Prerequisites
- Node.js 18 or higher
- Bitbucket account with [App Password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/jlromano/bitbucket-mcp.git
cd bitbucket-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Configure environment:**
```bash
cp .env.example .env
# Edit .env with your Bitbucket credentials
```
4. **Build the project:**
```bash
npm run build
```
## 🔐 Authentication Setup
### Creating a Bitbucket App Password
1. Log into your Bitbucket account
2. Navigate to **Personal Settings** → **App passwords**
3. Click **Create app password**
4. Select the following permissions:
- **Account**: Read
- **Workspace membership**: Read
- **Repositories**: Read, Write
- **Pull requests**: Read, Write
5. Copy the generated password
### Environment Configuration
Create a `.env` file with your credentials:
```env
BITBUCKET_USERNAME=your-username-or-email
BITBUCKET_APP_PASSWORD=your-app-password
BITBUCKET_WORKSPACE=default-workspace (optional)
```
## 📋 Configuration
### Claude Desktop
Add to your Claude configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"bitbucket": {
"command": "node",
"args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
"env": {
"BITBUCKET_USERNAME": "your-username",
"BITBUCKET_APP_PASSWORD": "your-app-password",
"BITBUCKET_WORKSPACE": "your-workspace"
}
}
}
}
```
### Other MCP-Compatible Applications
Install globally and run:
```bash
npm install -g bitbucket-mcp
bitbucket-mcp
```
## 🛠️ Available Tools
The server provides the following tools for LLM interaction:
| Tool | Description |
|------|-------------|
| `list_workspaces` | List all available workspaces |
| `list_repositories` | List repositories in a workspace |
| `get_repository` | Get repository details |
| `list_branches` | List repository branches |
| `get_branch` | Get branch details |
| `compare_branches` | Compare two branches |
| `list_pull_requests` | List pull requests with optional filters |
| `get_pull_request` | Get pull request details |
| `create_pull_request` | Create a new pull request |
| `approve_pull_request` | Approve a pull request |
| `merge_pull_request` | Merge a pull request |
| `add_pull_request_comment` | Add a comment to a pull request |
| `list_commits` | List repository commits |
| `get_commit` | Get commit details |
| `get_file_content` | Get file contents from repository |
| `search_code` | Search code in workspace |
## 💻 Development
### Project Structure
```
bitbucket-mcp/
├── src/
│ ├── index.ts # MCP server implementation
│ └── BitbucketClient.ts # Bitbucket API client
├── dist/ # Compiled JavaScript
├── .env.example # Environment variables template
├── package.json
├── tsconfig.json
└── README.md
```
### Development Commands
```bash
# Run in development mode with hot reload
npm run dev
# Build for production
npm run build
# Run linting
npm run lint
# Format code
npm run format
# Start production server
npm start
```
## 🤝 Usage Examples
Once configured, you can interact with your Bitbucket repositories through your LLM:
- "List all repositories in my workspace"
- "Show open pull requests in the main repository"
- "Create a pull request from feature/new-feature to main"
- "Get the content of README.md from the develop branch"
- "Search for 'authentication' in the codebase"
- "Compare develop and main branches"
- "Show recent commits with 'fix' in the message"
## 🔍 Troubleshooting
### Common Issues
**Authentication Failed**
- Verify your username (use email if that's your login)
- Ensure App Password is valid and has correct permissions
- Check that the App Password hasn't expired
**Workspace Not Found**
- Confirm workspace slug matches URL format: `bitbucket.org/WORKSPACE/`
- Verify you have access to the workspace
**Build Errors**
- Ensure Node.js 18+ is installed: `node --version`
- Clear node_modules and reinstall: `rm -rf node_modules && npm install`
- Rebuild the project: `npm run build`
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 🙏 Acknowledgments
- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Powered by [Bitbucket API](https://developer.atlassian.com/cloud/bitbucket/rest/)
- Inspired by the MCP community
## 📧 Support
For issues, questions, or suggestions, please [open an issue](https://github.com/jlromano/bitbucket-mcp/issues) on GitHub.
---
**Note**: This is not an official Atlassian product. Bitbucket is a trademark of Atlassian.
