JaviMaligno/mcp-server-bitbucket

MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.
Language Versions
This repository contains both **TypeScript** and **Python** implementations:
| Version | Directory | Status | Installation |
|---------|-----------|--------|--------------|
| **TypeScript** | /typescript | ✅ Recommended (Smithery) | npm install -g mcp-server-bitbucket |
| Python | /python | ✅ Stable | pipx install mcp-server-bitbucket |
> **Note**: The TypeScript version is used for Smithery deployments. Both versions provide identical functionality.
Features
- **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, view logs, stop
- **Branches**: list, get
- **Projects**: list, get
- **Commits**: list, get details, compare/diff between branches
- **Commit Statuses**: get build statuses, create status (CI/CD integration)
- **Deployments**: list environments, get environment details, deployment history
- **Webhooks**: list, create, get, delete
- **Tags**: list, create, delete
- **Branch Restrictions**: list, create, delete branch protection rules
- **Source Browsing**: read files, list directories without cloning
- **Repository Permissions**: manage user and group permissions
- **Pipeline Variables**: manage CI/CD environment variables
- **MCP Prompts**: reusable workflow templates (code review, release notes, etc.)
- **MCP Resources**: browsable workspace data
Quick Start
TypeScript (Recommended for Smithery)
Python
**Full Installation Guide** - Includes API token creation, permissions setup, and troubleshooting.
Hosted
If you'd rather not run the server yourself, a hosted deployment is available on
Fronteir AI.
Configuration
Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| BITBUCKET_WORKSPACE | ✅ | Bitbucket workspace slug |
| BITBUCKET_EMAIL | ✅ (basic auth) | Account email for Basic Auth |
| BITBUCKET_API_TOKEN | ✅ | Atlassian API token (Basic auth) |
| BITBUCKET_OAUTH_TOKEN | | Access token sent as Authorization: Bearer |
| BITBUCKET_AUTH_TYPE | | Force auth mode: basic or bearer (auto-detected) |
| API_TIMEOUT | | Request timeout in seconds (default: 30) |
| MAX_RETRIES | | Max retry attempts for rate limiting (default: 3) |
Authentication modes
Bitbucket Cloud has two credential families, and they do **not** share an auth scheme:
| Credential | Header | Configuration |
|------------|--------|---------------|
| Atlassian API token (ATATT...), tied to a personal account | Authorization: Basic base64(email:token) | BITBUCKET_EMAIL + BITBUCKET_API_TOKEN |
| Workspace / project / repository access token (ATCTT...), owned by the workspace | Authorization: Bearer | BITBUCKET_OAUTH_TOKEN |
Access tokens return **401 with Basic auth**, so the server picks the mode automatically:
1. BITBUCKET_AUTH_TYPE, when set, always wins.
2. Otherwise bearer is used when BITBUCKET_OAUTH_TOKEN is set, or when no BITBUCKET_EMAIL is configured.
3. Otherwise basic is used (the default for personal API tokens).
Bearer example — a company-owned workspace access token with no personal account involved:
Protecting the remote server (OAuth)
The stdio server runs on your machine with your own credential, so it needs no
protection. A **remote** deployment is different: it holds one shared credential
and serves whoever reaches it, so /mcp can be gated on a bearer token issued
by an external authorization server (Microsoft Entra ID, Okta, Auth0…).
| Variable | Description |
|----------|-------------|