Skip to main content
Glama
fnops

bitbucket-mcp-server

by fnops
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Bitbucket MCP Server

A community Model Context Protocol server for Bitbucket Cloud. Gives AI agents (Copilot, Claude, etc.) safe, typed access to repositories, branches, pull requests, and deployments.

Quick start

# 1 — Install
npm ci

# 2 — Configure (copy and fill in your credentials)
cp .env.example .env

# 3 — Build
npm run build

# 4 — Run
node build/index.js

Features

Area

Tools

Repositories

list_repositories, list_projects, list_branches, list_tags, get_branch_commits, clone_repository

Branches

create_branch

Pull Requests

create_pull_request, list_pull_requests, get_pull_request, approve_pull_request, decline_pull_request, merge_pull_request, get_pull_request_comments, add_pull_request_comment

Deployments

list_deployments, get_deployment

Configuration

Environment variables

Variable

Required

Default

Description

BITBUCKET_API_TOKEN

Yes*

—

API token (Bearer auth — recommended)

BITBUCKET_USERNAME

Yes*

—

Bitbucket account email (Basic auth — legacy)

BITBUCKET_APP_PASSWORD

Yes*

—

App Password (Basic auth — legacy)

BITBUCKET_WORKSPACE

Yes

—

Workspace slug

BITBUCKET_API_URL

No

https://api.bitbucket.org/2.0

API base URL (override for testing)

MCP_TRANSPORT

No

stdio

stdio (local dev) or http (VPC service)

MCP_PORT

No

3000

HTTP server port (only when MCP_TRANSPORT=http)

MCP_HOST

No

0.0.0.0

HTTP server bind address

LOG_LEVEL

No

info

fatal, error, warn, info, debug, trace

NODE_ENV

No

production

development, production, test

* Authentication: set BITBUCKET_API_TOKEN or both BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD. If both are provided, the API token takes priority.

MCP client configuration

Local (stdio — default)

Add this to your MCP client settings (VS Code, Claude Desktop, etc.):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      },
      "transportType": "stdio"
    }
  }
}

Remote (HTTP — VPC service)

Deploy the server with MCP_TRANSPORT=http and point clients to the HTTP endpoint:

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://your-mcp-host:3000/mcp",
      "transportType": "http"
    }
  }
}

The HTTP server exposes:

Endpoint

Method

Purpose

/health

GET

Health check (ALB/ECS probes)

/mcp

POST

MCP JSON-RPC requests

/mcp

GET

SSE stream for server-initiated messages

/mcp

DELETE

Session termination

Creating a Bitbucket App Password

Note: Bitbucket is deprecating App Passwords. Prefer API tokens (Repository or Workspace Access Tokens) for new setups.

  1. Go to https://bitbucket.org/account/settings/app-passwords/

  2. Click Create app password

  3. Select permissions:

    • Repositories: Read, Write, Admin

    • Pull requests: Read, Write

    • Account: Read

  4. Copy the generated password

Development

Prerequisites

  • Node.js 24+

  • npm

Scripts

npm run build          # Compile TypeScript → build/
npm run dev            # Watch mode (tsc --watch)
npm run typecheck      # Type-check without emitting
npm run lint           # ESLint
npm run lint:fix       # ESLint with auto-fix
npm run format         # Prettier write
npm run format:check   # Prettier check
npm run test           # Vitest (single run)
npm run test:watch     # Vitest (watch)
npm run test:coverage  # Vitest with coverage
npm run inspector      # MCP Inspector UI

Project structure

src/
├── index.ts               # Entry-point — McpServer setup & tool registration
├── config.ts              # Zod-validated environment config (singleton)
├── logger.ts              # Pino structured logger
├── httpClient.ts          # Axios instance w/ retry, rate-limit logging
├── errors.ts              # Custom error hierarchy
├── schemas.ts             # Zod input schemas for every tool
├── types.ts               # Bitbucket API response interfaces
├── *.test.ts              # Unit tests (Vitest)
└── handlers/
    ├── repository.ts      # Repos, branches, tags, commits, clone
    ├── branch.ts          # Branch creation
    ├── pullRequest.ts     # PR CRUD, review, merge, comments
    └── deployment.ts      # Deployment listing & details

Architecture highlights

  • MCP SDK 1.x high-level API — uses McpServer.tool() with native Zod schema registration (no manual JSON-Schema).

  • Zod everywhere — config validated at startup; tool inputs validated per-request.

  • Structured logging — pino with JSON output in production, pretty-print in development.

  • Automatic retries — axios-retry with exponential back-off for 429 / 5xx / network errors.

  • Rate-limit awareness — logs warnings when Bitbucket X-RateLimit-Remaining drops below threshold.

  • Custom error classes — ValidationError, BitbucketApiError, NotFoundError, ConfigError.

  • No any — fully typed handlers and schemas.

Docker

The Dockerfile defaults to HTTP mode (MCP_TRANSPORT=http) for containerised deployments.

# Build
docker build -t bitbucket-mcp-server .

# Run (HTTP mode — default in Docker)
docker run --env-file .env -p 3000:3000 bitbucket-mcp-server

Or using Docker Compose:

docker compose up

The Dockerfile uses a multi-stage build with node:24-slim, runs as a non-root user, and includes a HEALTHCHECK instruction.

Reliability

Concern

How it's handled

Transient API failures

3 retries w/ exponential back-off (1 s → 2 s → 4 s)

Rate limiting

429 responses are retried; X-RateLimit-* headers are logged

Invalid input

Zod rejects bad input before any API call is made

Missing config

Startup fails fast with a clear error listing all missing variables

Graceful shutdown

SIGINT / SIGTERM handlers close the MCP connection cleanly

Dual transport

stdio for local dev, http for VPC — same codebase

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/fnops/bitbucket-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server