# Bitbucket MCP Server

[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
[![MCP Protocol](https://img.shields.io/badge/MCP-1.0.4-purple)](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.