Bitbucket Server MCP

A Model Context Protocol (MCP) server that connects AI assistants to Bitbucket Server/Data Center. Review pull requests, manage repositories, search users, and interact with your Bitbucket instance through natural language in Claude and other AI assistants.

🚀 Quick Start

Get Your Bitbucket Server Credentials

1. Log into your Bitbucket Server instance
2. Go to Profile → Manage account → Personal access tokens
3. Click Create a token
4. Give it a name and select appropriate permissions:
   • Project permissions: Read (or Write for commenting)
   • Repository permissions: Read (or Write for commenting)
5. Copy the generated token
6. Note your Bitbucket Server URL (e.g., https://bitbucket.yourcompany.com)

Configuration

Claude Code

Add the server using the Claude Code CLI:

claude mcp add -s user \
    bitbucket-server \
    npx mcp-bitbucket-server@latest \
    -e "BITBUCKET_URL=https://bitbucket.yourcompany.com" \
    -e "BITBUCKET_TOKEN=your_personal_access_token"

Manual Configuration (Any MCP Client)

Alternatively, add this configuration to your MCP client's configuration file:

{
  "mcpServers": {
    "bitbucket-server": {
      "command": "npx",
      "args": ["mcp-bitbucket-server@latest"],
      "type": "stdio",
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "your_personal_access_token"
      }
    }
  }
}

✨ Features

• 👥 User Management - Search users and get profiles
• 📁 Project & Repository Discovery - List projects and repositories
• 🔍 Pull Request Review - Get PR details, changes, diffs, and activities
• 💬 Smart Comments - Add general, reply, and inline comments on PRs
• 📊 PR Inbox - See all PRs where you're a reviewer across all projects
• 🎯 Token Optimized - Responses optimized to reduce token usage
• 🔒 Secure Authentication - Uses Personal Access Tokens
• 🛡️ Simple & Direct - Minimal abstractions, direct API access

🛠️ Available Tools

The server provides 11 MCP tools for Bitbucket Server operations:

User Management

• bitbucket_get_user_profile - Get detailed user information
• bitbucket_get_all_users - List and search all users

Projects & Repositories

• bitbucket_list_projects - Discover available projects
• bitbucket_list_repositories - List repositories in a project

Pull Request Operations

• bitbucket_get_inbox_pull_requests - Get all PRs needing your review
• bitbucket_get_pull_request_changes - List all changed files in a PR
• bitbucket_get_pull_request_file_diff - Get structured line-by-line diff
• bitbucket_get_pull_request_activities - Get PR comments, approvals, and activity
• bitbucket_add_pr_comment - Add general, reply, or inline comments

💡 Example Queries

• "Show me all pull requests I need to review"
• "Get the changes in pull request #123 in the PROJ repository"
• "Show me the diff for src/main.ts in PR #456"
• "Add a comment on line 42 of src/app.ts suggesting we use const instead"
• "List all repositories in the DEV project"
• "Find users named John"
• "What are the recent activities on PR #789?"

🏗️ Development

From Source

# Clone and setup
git clone https://github.com/evrimalacan/mcp-bitbucket-server.git
cd mcp-bitbucket-server
npm install

# Build
npm run build

# Development mode
npm run dev

Adding New Tools

1. Check the Bitbucket Server Swagger documentation (BitbucketServerSwagger.json)
2. Create a new tool file in the appropriate domain folder under src/tools/
3. Export it from the domain's index.ts
4. Register it in src/tools/index.ts

See CLAUDE.md for detailed development guidelines.

🐛 Troubleshooting

Common Issues

"Authentication failed"

• Verify your Personal Access Token is correct
• Ensure the token has appropriate permissions

"Access forbidden"

• Check your Bitbucket user has permission for the resource
• Verify token permissions include required scopes

"Resource not found"

• Confirm the project key, repository slug, or PR ID is correct
• Check you have access to the specified resource

📚 Documentation

• Development Guide - Detailed development and contribution guide
• Bitbucket Server REST API - Official API reference
• Model Context Protocol - MCP specification

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Follow the development guide in CLAUDE.md
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🌟 Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: See CLAUDE.md for comprehensive guide

---

Built for developers who want AI assistance with Bitbucket Server