Submit
Unofficial-Warp

bitbucket-mcp

Community Unofficial-Warp
Updated

Remote MCP server for Bitbucket Cloud — Hono on Cloudflare Workers, built with Effect. Stateless: callers bring their own API token.

bitbucket-mcp

An MCP (Model Context Protocol) server that exposes Bitbucket Cloud repository and pull requestdata as tools consumable by any MCP-compatible client (Claude, Cursor, etc.).

This is a port of the original Go stdio server(bradlycarpenter/bitbucket-mcp) to a Hono app running onCloudflare Workers, built with Effect.

How it works

The worker serves the MCP streamable HTTP transport at POST /:workspace/mcp via @hono/mcp.It is fully stateless and stores no credentials of its own: each caller creates their ownBitbucket API token, sends it on every request, and the worker relays the call to the BitbucketAPI on their behalf. Every action is therefore attributed to the caller's own Bitbucket account.

Everything below the transport is Effect:

  • src/bitbucket/config.ts — BitbucketConfig service, built per request from the caller'sworkspace and Authorization header
  • src/bitbucket/client.ts — Bitbucket service wrapping the Bitbucket Cloud REST API onHttpClient, returning typed errors
  • src/bitbucket/domain.ts — Schema definitions used to decode (and trim) API responses
  • src/mcp/tool.ts — tool definitions whose parameters are Schemas; JSON Schema for the MCPtool list is derived from them
  • src/index.ts — a ManagedRuntime per request bridges Effect into the Hono handler

Tools

Tool Description
list_repositories List all repositories in the configured workspace
list_branches List branches for a repository
list_pull_requests List pull requests, optionally filtered by state
get_pull_request Get a specific pull request by ID
create_pull_request Create a new pull request, optionally as a draft
update_pull_request Update a pull request title and/or description
set_pr_draft Move a pull request to draft, or back to ready for review
list_pr_commits List commits on a pull request
list_pr_comments List all comments on a pull request
list_pr_activity Full activity stream for a pull request
get_pr_diff Unified diff for a pull request
get_pr_diffstat File-level change summary for a pull request
compare_branches_diff Unified diff between two branches
compare_branches_diffstat File-level diffstat between two branches
compare_branches_commits Commits in source branch not in destination branch

Setup page

GET / serves a setup page: enter your workspace, email and API token, and it generates theclaude mcp add command (and an equivalent JSON config) ready to copy. It also lists every toolwith its arguments, rendered from the same tools array the server registers, so it cannot drift.

The form is inert — there is no submit handler and no fetch. The base64 encoding happens inbtoa in the browser, so the token only ever leaves the machine on the MCP requests your clientmakes afterwards.

Request contract

The worker stores no credentials. Every request carries its own identity:
URL POST https://<worker>/<workspace-slug>/mcp
Header Authorization: Basic <base64 of email:api-token>

The Authorization header is forwarded verbatim to api.bitbucket.org; Bearer is accepted tooif you are using an OAuth access token. A request without credentials gets a 401, and aworkspace slug outside [A-Za-z0-9][A-Za-z0-9_.-]* gets a 400.

Because callers bring their own tokens, an unauthenticated request can do nothing, and the workernever sees more access than the token it was handed. Do not add request logging that capturesheaders — the credential is on every call.

Restricting which workspaces are served

Variable Required Purpose
ALLOWED_WORKSPACES no Comma-separated workspace slugs. Anything else gets a 404.

Set this on any deployment you don't want used as a general-purpose Bitbucket relay. Requests forother workspaces are refused before any credential is used, and the response is a bare 404 so itdoesn't reveal which workspaces the deployment serves. Matching ignores case.

Leaving it unset serves every workspace. That exposes no data — a caller still needs a token validfor whichever workspace they ask for — but it does let strangers spend your request quota.

npx wrangler secret put ALLOWED_WORKSPACES

Set it as a secret rather than a vars entry if your repository is public, so the slug isn'tcommitted.

Creating an API token

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click Create API token, label it, and copy the token — it is not shown again
  3. Base64-encode it together with your Atlassian account email:
printf '[email protected]:<api-token>' | base64

Required scopes:

Scope Purpose
read:repository:bitbucket List repositories and branches
read:pullrequest:bitbucket Read pull requests, commits, diffs, comments, and activity
write:pullrequest:bitbucket Create and update pull requests

Local development

pnpm install
pnpm dev

The endpoint is http://localhost:5173/<workspace-slug>/mcp.

Deploying

pnpm deploy

MCP client configuration

{
  "mcpServers": {
    "bitbucket": {
      "type": "http",
      "url": "https://<your-worker>.workers.dev/<workspace-slug>/mcp",
      "headers": {
        "Authorization": "Basic <base64 of email:api-token>"
      }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add --transport http bitbucket \
  https://<your-worker>.workers.dev/<workspace-slug>/mcp \
  --header "Authorization: Basic <base64 of email:api-token>"

MCP Server · Populars

MCP Server · New