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 Code.

🎯 38 tools available | ✅ 189 unit tests (92.9% overall, 95.5% core src coverage) | 🏗️ Modular architecture | 📦 TOON/JSON/text output formats

Official Documentation

Requirements

• Code Search: Enable at https://bitbucket.org/search for bb_search_code functionality
• Node.js: Version 18+ (native fetch API support required)
• 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 with scopes"
3. Enter a label (e.g., "Bitbucket MCP"), set expiry date, and click "Next"
4. Select "Bitbucket" in the app selection and click "Next"
5. In the scope actions, select "Read" and in the Results per page, select 20 or hgiher
6. Check all the checkboxes and click "Next"
7. Copy the generated token and use it as BITBUCKET_API_TOKEN
8. Use your Atlassian account email as BITBUCKET_EMAIL

Installation

Option 1: Install from NPM (Recommended)

npm install -g @tugudush/bitbucket-mcp

Updating to the latest version:

npm update -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": "your@email.com"
      }
    }
  }
}

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": "your@email.com"
      }
    }
  }
}

Claude Code

Using CLI:

claude mcp add --transport stdio \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_EMAIL=your@email.com \
  bitbucket-mcp -- npx @tugudush/bitbucket-mcp

Or add to .mcp.json (project scope):

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

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": "your@email.com"
      }
    }
  }
}

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": "your@email.com"
      }
    }
  }
}

Claude Code

Using CLI:

claude mcp add --transport stdio \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_EMAIL=your@email.com \
  bitbucket-mcp -- node /path/to/build/index.js

Or add to .mcp.json (project scope):

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

💡 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 (8 tools)

• bb_list_workspaces - Discover accessible workspaces
• bb_get_workspace - Get workspace details
• bb_list_repositories - List repositories across workspaces
• bb_get_repository - Get repository details
• bb_search_repositories - Find repositories by name/description
• 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)
• bb_get_file_history - Get commit history for specific files

🔀 Pull Requests (11 tools)

• bb_get_pull_requests - List all pull requests
• bb_get_pull_request - Get detailed PR information
• bb_get_pull_request_comments - List all comments on a PR
• bb_get_pull_request_comment - Get a single comment by ID
• bb_get_comment_thread - Get a comment thread with all nested replies
• bb_get_pull_request_activity - Track reviews, approvals, state changes
• bb_get_pull_request_diff - Get unified diff for a PR
• bb_get_pull_request_diffstat - Get per-file change statistics
• bb_get_pr_commits - List commits in a PR
• bb_get_pr_statuses - Get CI/CD build statuses for a PR
• bb_get_context - Get curated PR context bundle in a single call (metadata, diffstat, statuses, comments)

🌿 Branches & Commits (8 tools)

• bb_get_branches - List all branches
• bb_get_branch - Get detailed branch information
• bb_get_commits - List commit history
• bb_get_commit - Get detailed commit information
• bb_get_commit_statuses - Get CI/CD build statuses for a commit
• bb_get_merge_base - Find common ancestor between branches
• bb_get_tags - List repository tags
• bb_get_tag - Get detailed tag information

🔍 Diff & Comparison (2 tools)

• bb_get_diff - Get unified diff between commits
• bb_get_diffstat - Get per-file change statistics between commits

🚀 CI/CD Pipelines (4 tools)

• bb_list_pipelines - List pipeline runs
• bb_get_pipeline - Get detailed pipeline information
• bb_get_pipeline_steps - List pipeline steps/stages
• bb_get_pipeline_step_log - Get build logs for pipeline steps

🎫 Issues (2 tools)

• bb_get_issues - List repository issues
• bb_get_issue - Get detailed issue information

🔍 Search & Discovery (1 tool)

• bb_search_code - Advanced code search with language filtering

👤 User Information (2 tools)

• bb_get_user - Get user information by username or UUID
• bb_get_current_user - Get authenticated user information

Total: 38 tools across 8 categories

Output Formats & Filtering

All 38 tools support flexible output formatting and data filtering via two optional parameters:

Output Format (output_format)

Control how responses are returned:

Format	Description	Best For
text	Human-readable formatted output (default)	Debugging, human review
json	Pretty-printed JSON with 2-space indentation	Programmatic consumption, structured data
toon	Token-Oriented Object Notation — compact tabular format	LLM consumption (30-60% token savings)

TOON format significantly reduces token usage when AI assistants consume Bitbucket data, making it ideal for large responses like PR lists, commit histories, and file contents.

JMESPath Filtering (filter)

Apply JMESPath expressions to transform structured response data before format conversion:

# Extract just PR titles and authors
filter: "values[].{title: title, author: author.display_name}"

# Get only open PRs
filter: "values[?state=='OPEN']"

# Extract repository names
filter: "values[].full_name"

Filtering is applied before format conversion, so you can combine filter with any output_format.

Examples

Get repositories as compact TOON format:

bb_list_repositories workspace=myworkspace output_format=toon

Get PR details as JSON:

bb_get_pull_request workspace=myworkspace repo_slug=myrepo pull_request_id=123 output_format=json

Filter and format — get only PR titles in TOON:

bb_get_pull_requests workspace=myworkspace repo_slug=myrepo output_format=toon filter="values[].{id: id, title: title, state: state}"

Tip: When using this server with AI assistants, consider using output_format=toon for large responses to reduce token consumption by 30-60%.

Global Default Format

To set a default output format for all tools without specifying it per-call, set the BITBUCKET_DEFAULT_FORMAT environment variable:

{
  "env": {
    "BITBUCKET_API_TOKEN": "your-token",
    "BITBUCKET_EMAIL": "your@email.com",
    "BITBUCKET_DEFAULT_FORMAT": "toon"
  }
}

• If unset, defaults to text (backward compatible)
• Per-call output_format always takes priority over the env var
• Accepted values: text, json, toon

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"
• "Search for repositories containing 'keycloak' in myworkspace"

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 from develop branch"
• "Get the commit history for src/components/Header.tsx"

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 & Comments:

• "Show open pull requests for myworkspace/myrepo"
• "Get details for PR #123 in myworkspace/myrepo"
• "List all comments on PR #123"
• "Get comment #12345678 from PR #123 in myworkspace/myrepo"
• "Get the comment thread for comment #12345678 on PR #123"
• "Show me the diff for PR #123"
• "Get build statuses for PR #123"
• "Get full context for PR #123 in myworkspace/myrepo"
• "Get PR context from URL https://bitbucket.org/myworkspace/myrepo/pull-requests/123"
• "Get the open PR for branch feature/my-feature in myworkspace/myrepo"

Branches & Commits:

• "List all branches in myworkspace/myrepo"
• "Get details for the develop branch"
• "Show recent commits on main branch of myworkspace/myrepo"
• "Get commit details for abc123de"
• "Find the merge base between develop and main"
• "Show the diff between commits abc123 and def456"

Tags & Releases:

• "List all tags in myworkspace/myrepo"
• "Get details for tag v1.0.0"

Development

Build & Test Commands

npm run build    # TypeScript compilation
npm run watch    # Development mode with auto-rebuild
npm run ltf      # Lint → Format → Typecheck (recommended before commits)
npm run ltfb     # Lint → Typecheck → Format → Build (full pipeline)
node build/index.js  # Test server startup

Testing

The MCP server includes comprehensive test coverage:

Unit Tests: 189 tests across 12 test suites (92.9% overall, 95.5% on core src statement coverage)

• All 8 handler modules tested: repository, pullrequest, commit, diff, issue, pipeline, search, workspace
• Output format conversion tests: text, JSON, TOON, JMESPath filtering, edge cases
• Core modules tested: api, config, errors
• Uses mocked makeRequest/makeTextRequest with thorough edge case coverage
• Run npm test or jest --coverage for full coverage report

Integration Tests: 31 out of 38 tools verified (100% success rate on testable tools)

• Uses discovery-based approach with dynamic ID extraction
• Validates all major Bitbucket operations with real-world scenarios

To create your own tests:

1. Follow existing handler test patterns in src/__tests__/handlers/
2. Mock API calls using jest.mock for unit tests
3. For integration tests, load credentials from .vscode/mcp.json
4. Validate tool responses and error handling

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

Debugging

Enable debug logging to see internal state and API requests:

BITBUCKET_DEBUG=true node build/index.js

Debug output is printed to stderr and includes:

• Configuration details at startup
• Authentication method used
• API request/response details

Architecture

Modular design with handler registry pattern:

• src/handlers/ - Domain-specific tool handlers (repository, pullrequest, commit, diff, workspace, search, issue, pipeline)
• src/tools.ts - Tool definitions and handler routing
• src/schemas.ts - Zod validation schemas with API constants
• src/types.ts - TypeScript interfaces for Bitbucket API
• src/api.ts - Request handling with retry logic
• src/config.ts - Configuration management
• src/errors.ts - Custom error classes

See .github/copilot-instructions.md for detailed development guidelines.

Security & Limitations

• ✅ Read-only by design: No write/delete/modify operations possible at any level
• ✅ Runtime protection: makeRequest() blocks non-GET requests
• ✅ Safe for production: No destructive actions supported
• ✅ Authenticated access: Uses API tokens for private repositories
• ✅ Type-safe: Zod validation and TypeScript interfaces throughout
• ✅ 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
• ✅ Error handling: Context-aware error messages with helpful suggestions
• ⚠️ Rate limiting: Subject to Bitbucket API limits (no custom throttling)
• ⚠️ Code search: Requires enablement in Bitbucket account settings at https://bitbucket.org/search
• ⚠️ File size limits: Large files handled with pagination (up to 10,000 lines per request)

Development Status

✅ Production Ready - 189 unit tests (92.9% overall, 95.5% on core src coverage), 31/38 integration tests verified

Recent Updates (2026-04):

• ✅ bb_get_context tool — curated PR context bundle in a single call (metadata, diffstat, statuses, comments)
• ✅ TOON output format — compact tabular format reducing LLM token consumption by 30-60%
• ✅ JSON output format — pretty-printed structured data for programmatic use
• ✅ JMESPath filtering — powerful data transformation on all 38 tools via filter parameter
• ✅ Comprehensive unit tests for all 8 handler modules (189 tests, 12 suites)
• ✅ Jest coverage tooling fixed — jest --coverage fully operational
• ✅ Repository search uses server-side BBQL filtering (no longer limited to single page)
• ✅ Comment thread pagination fetches all pages for large PRs via fetchAllPages()
• ✅ Fixed bb_get_user to use correct GET /users/{selected_user} endpoint
• ✅ Removed bb_list_user_pull_requests (non-existent Bitbucket API v2.0 endpoint)
• ✅ 38 tools covering all major Bitbucket operations
• ✅ Type-safe with Zod validation and TypeScript interfaces

We welcome contributions and feedback!

API Coverage

The server implements 38 tools covering all major Bitbucket Cloud API v2.0 endpoints (read-only):

• Workspaces API - Workspace discovery and information
• Repositories API - Repository listing, details, browsing, and search
• Source API - File content access with pagination, file history
• Pull Requests API - PR management, comments, threads, activity, diffs, commits, statuses, context bundles
• Branches API - Branch listing, details, and comparison
• Commits API - Commit history, details, and statuses
• Tags API - Tag listing and details
• Diff API - Unified diffs and diffstats between commits
• Issues API - Issue listing and details
• Search API - Code search with language filtering and match highlighting
• Users API - User and authenticated user information
• Pipelines API - CI/CD pipeline information (read-only)

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes:
   • Maintain read-only design principles
   • Follow the handler registry pattern (see src/handlers/)
   • Add TypeScript interfaces and Zod schemas
   • Use typed makeRequest<T>() calls
   • Format responses as readable text
4. Add tests if applicable (see test suite patterns)
5. Run npm run ltfb before committing
6. Submit a pull request

See .github/copilot-instructions.md for detailed development guidelines.

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):

• ✅ 38 comprehensive tools COMPLETE
• ✅ Comment threads with nested replies COMPLETE
• ✅ Comprehensive test suite COMPLETE
• ✅ Modular handler architecture COMPLETE
• ✅ TOON/JSON output formats + JMESPath filtering COMPLETE
• ✅ PR context bundle (bb_get_context) COMPLETE
• Repository statistics and analytics
• Enhanced search capabilities with more filter options
• Webhook information retrieval (read-only)
• Extended pipeline details and logs
• Repository comparison and analytics tools
• Advanced code search with AI-powered insights