bitbucket-mcp

An MCP (Model Context Protocol) server that exposes Bitbucket Cloud repository and pull request data 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 on Cloudflare 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 own Bitbucket API token, sends it on every request, and the worker relays the call to the Bitbucket API 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's workspace and Authorization header
• src/bitbucket/client.ts — Bitbucket service wrapping the Bitbucket Cloud REST API on HttpClient, 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 MCP tool 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
update_pull_request	Update a pull request title and/or description
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 the claude mcp add command (and an equivalent JSON config) ready to copy. It also lists every tool with 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 in btoa in the browser, so the token only ever leaves the machine on the MCP requests your client makes 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 too if you are using an OAuth access token. A request without credentials gets a 401, and a workspace 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 worker never sees more access than the token it was handed. Do not add request logging that captures headers — 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 for other workspaces are refused before any credential is used, and the response is a bare 404 so it doesn'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 valid for 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't committed.

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 'you@yourcompany.com:<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>"