MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client. This repository contains both TypeScript and Python implementations: - Repositories: get, create, delete, list, update (move to project, rename) - Pull Requests: create, get, list, merge, approve, decline, request changes, comments, diff - Pipelines: trigger, get status, list, vi
Add this skill
npx mdskills install JaviMaligno/mcp-server-bitbucketComprehensive Bitbucket API integration with 58 well-documented tools covering repos, PRs, pipelines, and CI/CD workflows
1# Bitbucket MCP Server23<!-- mcp-name: io.github.JaviMaligno/bitbucket -->45[](https://github.com/JaviMaligno/mcp-server-bitbucket/actions/workflows/ci.yml)6[](https://pypi.org/project/mcp-server-bitbucket/)7[](https://www.npmjs.com/package/mcp-server-bitbucket)8[](https://opensource.org/licenses/MIT)910MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.1112## Language Versions1314This repository contains both **TypeScript** and **Python** implementations:1516| Version | Directory | Status | Installation |17|---------|-----------|--------|--------------|18| **TypeScript** | `/typescript` | ✅ Recommended (Smithery) | `npm install -g mcp-server-bitbucket` |19| Python | `/python` | ✅ Stable | `pipx install mcp-server-bitbucket` |2021> **Note**: The TypeScript version is used for Smithery deployments. Both versions provide identical functionality.2223## Features2425- **Repositories**: get, create, delete, list, update (move to project, rename)26- **Pull Requests**: create, get, list, merge, approve, decline, request changes, comments, diff27- **Pipelines**: trigger, get status, list, view logs, stop28- **Branches**: list, get29- **Projects**: list, get30- **Commits**: list, get details, compare/diff between branches31- **Commit Statuses**: get build statuses, create status (CI/CD integration)32- **Deployments**: list environments, get environment details, deployment history33- **Webhooks**: list, create, get, delete34- **Tags**: list, create, delete35- **Branch Restrictions**: list, create, delete branch protection rules36- **Source Browsing**: read files, list directories without cloning37- **Repository Permissions**: manage user and group permissions38- **Pipeline Variables**: manage CI/CD environment variables39- **MCP Prompts**: reusable workflow templates (code review, release notes, etc.)40- **MCP Resources**: browsable workspace data4142## Quick Start4344### TypeScript (Recommended for Smithery)4546```bash47# Install globally48npm install -g mcp-server-bitbucket4950# Or run directly with npx51npx mcp-server-bitbucket52```5354### Python5556```bash57# Install with pipx58pipx install mcp-server-bitbucket5960# Configure Claude Code61claude mcp add bitbucket -s user \62 -e BITBUCKET_WORKSPACE=your-workspace \63 -e BITBUCKET_EMAIL=your-email@example.com \64 -e BITBUCKET_API_TOKEN=your-api-token \65 -- mcp-server-bitbucket66```6768**[Full Installation Guide](https://github.com/JaviMaligno/mcp-server-bitbucket/blob/main/docs/INSTALLATION.md)** - Includes API token creation, permissions setup, and troubleshooting.6970## Configuration7172### Environment Variables7374| Variable | Required | Description |75|----------|----------|-------------|76| `BITBUCKET_WORKSPACE` | ✅ | Bitbucket workspace slug |77| `BITBUCKET_EMAIL` | ✅ | Account email for Basic Auth |78| `BITBUCKET_API_TOKEN` | ✅ | Repository access token |79| `API_TIMEOUT` | | Request timeout in seconds (default: 30) |80| `MAX_RETRIES` | | Max retry attempts for rate limiting (default: 3) |8182### Claude Code CLI8384```bash85# TypeScript version86claude mcp add bitbucket -s user \87 -e BITBUCKET_WORKSPACE=your-workspace \88 -e BITBUCKET_EMAIL=your-email@example.com \89 -e BITBUCKET_API_TOKEN=your-api-token \90 -- npx mcp-server-bitbucket9192# Python version93claude mcp add bitbucket -s user \94 -e BITBUCKET_WORKSPACE=your-workspace \95 -e BITBUCKET_EMAIL=your-email@example.com \96 -e BITBUCKET_API_TOKEN=your-api-token \97 -- mcp-server-bitbucket98```99100### Cursor IDE101102Add to `~/.cursor/mcp.json`:103104```json105{106 "mcpServers": {107 "bitbucket": {108 "command": "npx",109 "args": ["mcp-server-bitbucket"],110 "env": {111 "BITBUCKET_WORKSPACE": "your-workspace",112 "BITBUCKET_EMAIL": "your-email@example.com",113 "BITBUCKET_API_TOKEN": "your-api-token"114 }115 }116 }117}118```119120## Available Tools (58 total)121122### Repositories123| Tool | Description |124|------|-------------|125| `list_repositories` | List and search repositories |126| `get_repository` | Get repository details |127| `create_repository` | Create a new repository |128| `delete_repository` | Delete a repository |129| `update_repository` | Update repo settings |130131### Pull Requests132| Tool | Description |133|------|-------------|134| `list_pull_requests` | List PRs |135| `get_pull_request` | Get PR details |136| `create_pull_request` | Create a new PR |137| `merge_pull_request` | Merge a PR |138| `approve_pr` | Approve a PR |139| `unapprove_pr` | Remove approval |140| `request_changes_pr` | Request changes |141| `decline_pr` | Decline a PR |142| `list_pr_comments` | List comments |143| `add_pr_comment` | Add comment |144| `get_pr_diff` | Get the diff |145146### Pipelines147| Tool | Description |148|------|-------------|149| `list_pipelines` | List recent runs |150| `get_pipeline` | Get status |151| `get_pipeline_logs` | View logs |152| `trigger_pipeline` | Trigger a run (supports custom pipelines and commit triggers) |153| `stop_pipeline` | Stop pipeline |154| `list_pipeline_variables` | List variables |155| `get_pipeline_variable` | Get variable |156| `create_pipeline_variable` | Create variable |157| `update_pipeline_variable` | Update variable |158| `delete_pipeline_variable` | Delete variable |159160#### trigger_pipeline Parameters161162| Parameter | Type | Description |163|-----------|------|-------------|164| `repo_slug` | string | Repository slug (required) |165| `branch` | string | Branch to run on (default: main). Mutually exclusive with `commit` |166| `commit` | string | Commit hash to run on. Mutually exclusive with `branch` |167| `custom_pipeline` | string | Name from `custom:` section in bitbucket-pipelines.yml |168| `variables` | array | Variables as `[{key, value, secured?}]` |169170**Examples:**171```python172# Default pipeline on main173trigger_pipeline(repo_slug="my-repo")174175# Custom pipeline176trigger_pipeline(repo_slug="my-repo", custom_pipeline="deploy-staging")177178# Custom pipeline on specific commit with variables179trigger_pipeline(180 repo_slug="my-repo",181 commit="abc123def",182 custom_pipeline="deploy-prod",183 variables=[184 {"key": "ENV", "value": "production"},185 {"key": "SECRET", "value": "xxx", "secured": True}186 ]187)188```189190### Branches, Commits, Tags191| Tool | Description |192|------|-------------|193| `list_branches` | List branches |194| `get_branch` | Get branch details |195| `list_commits` | List commits |196| `get_commit` | Get commit details |197| `compare_commits` | Compare branches |198| `get_commit_statuses` | Get build statuses |199| `create_commit_status` | Report CI status |200| `list_tags` | List tags |201| `create_tag` | Create a tag |202| `delete_tag` | Delete a tag |203204### And more...205- Deployments: `list_environments`, `get_environment`, `list_deployment_history`206- Webhooks: `list_webhooks`, `create_webhook`, `get_webhook`, `delete_webhook`207- Branch Restrictions: `list_branch_restrictions`, `create_branch_restriction`, `delete_branch_restriction`208- Source Browsing: `get_file_content`, `list_directory`209- Permissions: User and group permission management (8 tools)210- Projects: `list_projects`, `get_project`211212## MCP Prompts213214Reusable workflow templates:215216| Prompt | Description |217|--------|-------------|218| `code_review` | Comprehensive PR code review |219| `release_notes` | Generate changelog between versions |220| `pipeline_debug` | Debug failed CI/CD pipelines |221| `repo_summary` | Complete repository status overview |222223## MCP Resources224225Browsable workspace data:226227| Resource URI | Description |228|--------------|-------------|229| `bitbucket://repositories` | List all repos |230| `bitbucket://repositories/{repo}` | Repository details |231| `bitbucket://repositories/{repo}/branches` | Branch list |232| `bitbucket://repositories/{repo}/pull-requests` | Open PRs |233| `bitbucket://projects` | List all projects |234235## Development236237### TypeScript238239```bash240cd typescript241npm install242npm run build243npm run dev # Watch mode244```245246### Python247248```bash249cd python250uv sync251uv run python -m src.server252```253254## Creating a Bitbucket API Token2552561. Go to your repository in Bitbucket2572. Navigate to **Repository settings** > **Access tokens**2583. Click **Create Repository Access Token**2594. Select permissions:260 - **Repository**: Read, Write, Admin, Delete261 - **Pull requests**: Read, Write262 - **Pipelines**: Read, Write2635. Copy the token immediately264265## Author266267Built by [Javier Aguilar](https://www.javieraguilar.ai) - AI Agent Architect specializing in multi-agent orchestration and MCP development.268269## License270271MIT272
Full transparency — inspect the skill content before installing.