Bamboo MCP Server

Bamboo MCP Server

A Model Context Protocol server that exposes a self-hosted Atlassian Bamboo instance to AI assistants — Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP client.

Ask *"who deployed CHECKOUT to staging and did it pass?"* instead of clicking through the Bamboo UI.

Read-only by design. Every tool is registered behind a policy engine that enforces a GET-only floor. This server cannot trigger a build, start a deployment, or change anything in Bamboo.

---

⚠️ About self-hosted Bamboo

Atlassian has announced the end of support for Bamboo Data Center in 2029. If you are starting a new CI/CD project, you should be looking at a supported platform instead — check Atlassian's end-of-life policy for the current dates.

That said, plenty of organisations are still running Bamboo Server / Data Center today and will be for years, often with hundreds of plans and deployment projects accumulated over a decade. This project exists for those teams: if you are living with Bamboo until the migration lands, this makes the day-to-day "what's deployed where, and who broke it" questions a lot cheaper to answer.

Contributions are welcome, but be aware you are building on a platform with a known sunset.

---

Contents

• Features
• Quick start
• Configuration
• Connecting an MCP client
• Plan context — teaching it your conventions
• Security model
• Example prompts
• Important points & known limitations
• Development
• License

---

Features

31 read-only Bamboo tools

Server & projects (5)

Plans & branches (5)

Builds (7)

Deployments (8)

Plan context — the "smart" tools (6)

These are what make the server useful rather than just a REST wrapper. They read a YAML file describing *your* plan-key and environment naming conventions, so the model can go from a human reference to a Bamboo key without you spelling it out.

Bitbucket credential storage (4) — optional, see limitations

bitbucket_add_repo, bitbucket_get_repo, bitbucket_list_repos, bitbucket_delete_repo.

Stores repository URL/username/token in ~/.bamboo-mcp/bitbucket.json (mode 0600, tokens masked on read). Nothing else in the server consumes this — Bitbucket links in build results are built from the BITBUCKET_URL environment variable. See limitations.

35 tools total. The full surface — names, descriptions and JSON Schemas — is generated into tools.json, and bamboo-mcp --list-tools prints the same payload without needing a Bamboo connection. See the tool manifest.

9 prompt templates

MCP prompts give the model a structured plan for common workflows, so you get consistent output instead of ad-hoc tool flailing.

• = required

Other

• Two transports — stdio for desktop clients, sse (HTTP) for containers and remote access.
• Startup validation — config completeness, URL format, network reachability, token validity, transport sanity. Skippable with SKIP_VALIDATION=true.
• Security layer — GET-only floor, per-tool rate limits, result caps, response size limits, prompt-injection scanning. See Security model.
• Proxy support — BAMBOO_PROXY for corporate networks.
• Declared tool surface — tools.json and --list-tools, generated from the catalog and verified in CI, with a test that calls every declared tool. See Tests.

---

Quick start

Requires Go 1.23+ and a Bamboo personal access token.

git clone https://github.com/hmdmph/bamboo-mcp.git

cd bamboo-mcp make build # → bin/bamboo-mcp

export BAMBOO_URL=https://bamboo.example.com export BAMBOO_TOKEN=your_personal_access_token

./bin/bamboo-mcp # stdio mode

Getting a token: Bamboo → your profile → *Personal access tokens* → create. Read permission on the projects you care about is enough; this server never writes.

Docker / Podman

Prebuilt multi-arch images (linux/amd64, linux/arm64) are published to GHCR on every release:

docker run --rm -p 8080:8080 \

-e BAMBOO_URL=https://bamboo.example.com \ -e BAMBOO_TOKEN=your_token \ ghcr.io/hmdmph/bamboo-mcp:latest

Tags: latest, 1, 1.2, 1.2.3. Or build it yourself:

make docker-build

make docker-run-sse # detached, SSE on :8080

DOCKER_IMAGE=myregistry/bamboo-mcp DOCKER_TAG=v1.0.0 HTTP_PORT=9090 make docker-run-sse make docker-logs make docker-stop

# docker-compose.yml

services: bamboo-mcp: image: bamboo-mcp:latest ports: ["8080:8080"] environment: BAMBOO_URL: https://bamboo.example.com BAMBOO_TOKEN: your-token MCP_TRANSPORT: sse MCP_BASE_URL: http://bamboo-mcp:8080 restart: unless-stopped

Behind a corporate CA? The Dockerfile has commented-out lines near the top for copying your own PEM files into the image — drop them in certs/ and uncomment.

---

Configuration

All configuration is environment variables. Copy .env.example to .env.dev to keep them out of git.

Note on logging: in stdio mode, stdout carries the MCP protocol stream. All logging goes to stderr — never add fmt.Println to a handler.

---

Connecting an MCP client

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "bamboo": { "command": "/absolute/path/to/bamboo-mcp/bin/bamboo-mcp", "env": { "BAMBOO_URL": "https://bamboo.example.com", "BAMBOO_TOKEN": "your_personal_access_token" } } } }

Claude Code

claude mcp add bamboo /absolute/path/to/bin/bamboo-mcp \

-e BAMBOO_URL=https://bamboo.example.com \ -e BAMBOO_TOKEN=your_personal_access_token

Cursor / Windsurf

Same shape as Claude Desktop, in the client's MCP settings file.

Remote (SSE)

{

"mcpServers": { "bamboo": { "url": "http://your-server:8080/sse" } } }

The SSE server exposes /sse and /message. It has no authentication of its own — see limitations.

---

Plan context — teaching it your conventions

This is the part worth spending ten minutes on.

Most Bamboo estates encode meaning in their plan keys and environment names — something like PROJ-CHECKOUTAPP with environments called staging_network_checkout_deploy. Out of the box an AI assistant has no idea what any of that means. context.yaml tells it.

On first run a starter file is written to ~/.bamboo-mcp/context.yaml. It ships deliberately generic placeholders — the feature only becomes useful once you describe your own conventions. A fully commented, worked example lives in examples/context.yaml.