Bitbucket MCP Server

A read-only Model Context Protocol (MCP) server that provides secure access to Bitbucket repositories, pull requests, issues, and more. Integrates seamlessly with VS Code GitHub Copilot, Cursor, and Claude Desktop.

Requirements

• Code Search: Enable at https://bitbucket.org/search for bb_search_code functionality
• Node.js: Version 16+ with ES modules support
• Authentication: API token + email

💡 How to create an API Token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Enter a label (e.g., "Bitbucket MCP Server")
4. Copy the generated token and use it as BITBUCKET_API_TOKEN
5. Use your Atlassian account email as BITBUCKET_EMAIL

Installation

Option 1: Install from NPM (Recommended)

npm install -g @tugudush/bitbucket-mcp

Option 2: Build from Source

git clone https://github.com/tugudush/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build

Quick Start

Integration

Configure your MCP client with authentication credentials.

Option A: Using NPM Global Installation (Recommended)

After installing with npm install -g @tugudush/bitbucket-mcp:

VS Code GitHub Copilot

// .vscode/mcp.json
{
  "servers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "bitbucket-mcp",
      "env": {
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_EMAIL": "[email protected]"
      }
    }
  }
}

Cursor

// ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)
{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "bitbucket-mcp",
      "env": {
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_EMAIL": "[email protected]"
      }
    }
  }
}

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@tugudush/bitbucket-mcp"],
      "env": {
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_EMAIL": "[email protected]"
      }
    }
  }
}

Option B: Using Local Build (For Development)

If you built from source:

VS Code GitHub Copilot

// .vscode/mcp.json
{
  "servers": {
    "bitbucket-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_EMAIL": "[email protected]"
      }
    }
  }
}

Cursor

// ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)
{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_EMAIL": "[email protected]"
      }
    }
  }
}

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/build/index.js"],
      "env": {
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_EMAIL": "[email protected]"
      }
    }
  }
}

💡 Tips:

• Option A (NPM): Much simpler setup, no paths to manage, automatic updates available
• Option B (Local): Replace /path/to/build/index.js with the absolute path to your built server
• Add your actual Bitbucket credentials to access private repositories

Features

Repository Management

• bb_list_workspaces - Discover accessible workspaces
• bb_list_repositories - List repositories across workspaces
• bb_get_repository - Get repository details
• bb_browse_repository - Explore directory structure (supports branches with slashes like feature/SSP-1024)
• bb_get_file_content - Read files with pagination (1-10,000 lines)

Pull Requests & Issues

• bb_get_pull_requests, bb_get_pull_request - Browse pull requests
• bb_get_pull_request_comments, bb_get_pull_request_activity - Track reviews
• bb_get_issues, bb_get_issue - Monitor issues

Version Control

• bb_get_branches, bb_get_commits - Explore repository history

Search & Discovery

• bb_search_code - Advanced code search with language filtering
• bb_search_repositories - Find repositories

User & Workspace Info

• bb_get_user, bb_get_current_user - User information
• bb_get_workspace - Workspace details

Usage Examples

Repository Discovery:

• "List all my accessible workspaces"
• "Browse the root directory of myworkspace/myrepo"
• "Browse the tests directory in feature/deployment-fixes branch"

Advanced File Operations:

• "Read lines 100-200 of src/app.py from myworkspace/myrepo"
• "Get the first 50 lines of README.md"
• "Show me the package.json file with pagination"

Code Search:

• "Search for 'authentication' code in myworkspace/myrepo"
• "Find all functions containing 'validate' in myworkspace/myrepo"
• "Search for TypeScript interfaces in myworkspace/myrepo"
• "Look for 'TODO' comments in myworkspace/myrepo"

Pull Requests & Issues:

• "List repositories in myworkspace"
• "Show open pull requests for myworkspace/myrepo"
• "Get README.md from myworkspace/myrepo"
• "Show recent commits on main branch of myworkspace/myrepo"

Development

npm run ltfb     # Lint + Typecheck + Format + Build
npm run watch   # Development mode
node build/index.js  # Test server

VS Code Integration:

• Install GitHub Copilot extensions
• Use provided .vscode/ configuration
• Open Copilot Chat with Ctrl+Alt+I
• Try: using bitbucket, list repositories in myworkspace

Security & Limitations

• ✅ Read-only by design: No write/delete/modify operations possible
• ✅ Safe for production: No destructive actions supported
• ✅ Authenticated access: Uses API tokens or App Passwords for private repos
• ✅ Branch support: Handles branch names with special characters (e.g., feature/SSP-1024)
• ✅ Dynamic commit resolution: Automatically resolves branch names to commit SHAs for subdirectory browsing
• ⚠️ Rate limiting: Subject to Bitbucket API limits
• ⚠️ Code search: Requires enablement in Bitbucket account settings
• ⚠️ File size limits: Large files may be truncated

Development Status

🚧 This project is under active development and may contain incomplete features or breaking changes. We welcome contributions and feedback!

API Coverage

The server implements tools for the most commonly used Bitbucket API endpoints:

• Repositories API (read-only operations)
• Pull Requests API (read-only operations)
  • Pull request details and listing
  • Pull request comments (inline and general)
  • Pull request activity (reviews, approvals, state changes)
• Issues API (read-only operations)
• Source API (file content access)
• Search API (code search with language filtering and match highlighting)
• Users API (user information)
• Workspaces API (workspace information)
• Branches API (branch listing and information)
• Commits API (commit history and details)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes (maintaining read-only nature)
4. Add tests if applicable
5. Submit a pull request

Support

If you find this project helpful, please consider supporting its development:

Solana (SOL)

CWZccD3Ny3XotFZtnkcyzP3hapmu3ExknN1PF4rEvP3u

You can also run npm fund in your project to see all funding information.

Roadmap

Future enhancements (all read-only):

• Repository statistics and analytics
• Enhanced search capabilities with more filter options
• Webhook information retrieval
• Pipeline status (read-only)
• More detailed branch and commit information
• Repository comparison tools
• Advanced code search filters and sorting