@tugudush/bitbucket-mcp

v3.7.1

Published

11 days ago

A Model Context Protocol server for Bitbucket with read-only operations

0High
0Medium
0Low

tugudush

mcp model-context-protocol bitbucket api ai llm

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 | ✅ 184 unit tests (95.5% 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:
Go to https://id.atlassian.com/manage-profile/security/api-tokens
Click "Create API token with scopes"
Enter a label (e.g., "Bitbucket MCP"), set expiry date, and click "Next"
Select "Bitbucket" in the app selection and click "Next"
In the scope actions, select "Read" and in the Results per page, select 20 or hgiher
Check all the checkboxes and click "Next"
Copy the generated token and use it as BITBUCKET_API_TOKEN
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": "[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 Code

Using CLI:

claude mcp add --transport stdio \
  --env BITBUCKET_API_TOKEN=your-token \
  --env [email protected] \
  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": "[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 Code

Using CLI:

claude mcp add --transport stdio \
  --env BITBUCKET_API_TOKEN=your-token \
  --env [email protected] \
  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": "[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 (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": "[email protected]",
    "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: 184 tests across 12 test suites (95.5% 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:

Follow existing handler test patterns in src/__tests__/handlers/
Mock API calls using jest.mock for unit tests
For integration tests, load credentials from .vscode/mcp.json
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 - 184 unit tests (95.5% 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 (184 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:

Fork the repository
Create a feature branch
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
Add tests if applicable (see test suite patterns)
Run npm run ltfb before committing
Submit a pull request