Lynx Bitbucket MCP

A Model Context Protocol (MCP) server that exposes the Bitbucket Cloud REST API v2 as 52 tools, enabling AI assistants to interact with your Bitbucket workspaces, repositories, pull requests, pipelines, and more.

npm package: lynx-bitbucket-mcp

Prerequisites

• Node.js 18+
• A Bitbucket Cloud account with an App Password

Token permissions required: Repositories (read/write), Pull Requests (read/write), Pipelines (read/write), Webhooks (read/write)

Step 1 — Get your Bitbucket token

1. Log in to Bitbucket → Personal settings → App passwords
2. Click Create app password, give it a label, and select the permissions above
3. Copy the generated token — you'll use it as BITBUCKET_TOKEN below

Step 2 — Add to your AI tool

Pick your tool below. In every config, replace your_token_here with your actual token.

Claude Desktop

Config file location:

• macOS/Linux: ~/.config/claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lynx-bitbucket-mcp": {
      "command": "npx",
      "args": ["-y", "lynx-bitbucket-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

Add via the claude mcp add command:

claude mcp add --name lynx-bitbucket-mcp --command "npx" --args "-y,lynx-bitbucket-mcp" --env "BITBUCKET_TOKEN=your_token_here"

Or manually edit ~/.claude.json:

{
  "mcpServers": {
    "lynx-bitbucket-mcp": {
      "command": "npx",
      "args": ["-y", "lynx-bitbucket-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Code. The bb_* tools will be available in your session.

Cursor

Edit ~/.cursor/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "lynx-bitbucket-mcp": {
      "command": "npx",
      "args": ["-y", "lynx-bitbucket-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Cursor and verify under Settings → MCP.

VS Code (GitHub Copilot / MCP extension)

Add to your user settings.json (Ctrl+Shift+P → "Open User Settings JSON"):

{
  "mcp.servers": {
    "lynx-bitbucket-mcp": {
      "command": "npx",
      "args": ["-y", "lynx-bitbucket-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your_token_here"
      }
    }
  }
}

For workspace-only setup, add to .vscode/mcp.json:

{
  "servers": {
    "lynx-bitbucket-mcp": {
      "command": "npx",
      "args": ["-y", "lynx-bitbucket-mcp"],
      "env": {
        "BITBUCKET_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools (52)

Repositories (7)

| Tool | Description | |------|-------------| | bb_list_repositories | List repositories in a workspace | | bb_get_repository | Get repository details | | bb_create_repository | Create a new repository | | bb_update_repository | Update repository settings | | bb_list_watchers | List repository watchers | | bb_list_forks | List repository forks | | bb_list_repository_permissions | List user permissions |

Pull Requests (11)

| Tool | Description | |------|-------------| | bb_list_pullrequests | List pull requests | | bb_get_pullrequest | Get PR details | | bb_create_pullrequest | Create a pull request | | bb_update_pullrequest | Update a pull request | | bb_merge_pullrequest | Merge a pull request | | bb_approve_pullrequest | Approve a pull request | | bb_unapprove_pullrequest | Remove approval | | bb_list_pr_comments | List PR comments | | bb_add_pr_comment | Add a comment to a PR | | bb_list_pr_commits | List commits in a PR | | bb_get_pr_diff | Get PR diff |

Commits (5)

| Tool | Description | |------|-------------| | bb_list_commits | List commits on a branch | | bb_get_commit | Get commit details | | bb_get_commit_diff | Get commit diff | | bb_list_commit_statuses | List CI/CD statuses for a commit | | bb_create_commit_status | Post a CI/CD status to a commit |

Branches (6)

| Tool | Description | |------|-------------| | bb_list_branches | List branches | | bb_get_branch | Get branch details | | bb_create_branch | Create a branch | | bb_list_branch_restrictions | List branch protection rules | | bb_create_branch_restriction | Create a branch protection rule | | bb_update_branch_restriction | Update a branch protection rule |

Source / Files (3)

| Tool | Description | |------|-------------| | bb_get_file_content | Get raw file content | | bb_list_directory | List files in a directory | | bb_get_file_history | Get commit history for a file |

Pipelines (10)

| Tool | Description | |------|-------------| | bb_list_pipelines | List pipeline runs | | bb_get_pipeline | Get pipeline details | | bb_trigger_pipeline | Trigger a pipeline | | bb_stop_pipeline | Stop a running pipeline | | bb_list_pipeline_steps | List steps in a pipeline | | bb_get_pipeline_step | Get step details | | bb_get_step_log | Get step log output | | bb_list_pipeline_variables | List pipeline variables | | bb_create_pipeline_variable | Create a pipeline variable | | bb_update_pipeline_variable | Update a pipeline variable |

Deployments (6)

| Tool | Description | |------|-------------| | bb_list_deployments | List deployments | | bb_get_deployment | Get deployment details | | bb_list_environments | List deployment environments | | bb_get_environment | Get environment details | | bb_create_environment | Create a deployment environment | | bb_update_environment | Update a deployment environment |

Webhooks (4)

| Tool | Description | |------|-------------| | bb_list_webhooks | List webhooks | | bb_get_webhook | Get webhook details | | bb_create_webhook | Create a webhook | | bb_update_webhook | Update a webhook |

Example usage

Once connected, you can ask your AI assistant things like:

• "List all open pull requests in workspace my-team, repo my-api"
• "Show me the diff for PR #42"
• "Trigger the main branch pipeline for repo my-app"
• "Get the content of src/index.ts from the develop branch"
• "Create a branch restriction to prevent force-pushing to main"