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

Related MCP server: bitbucket-mcp-server

Tools

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:

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

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:

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>"