buildkite-mcp-server 🚀

Model Context Protocol (MCP) server exposing Buildkite data (pipelines, builds, jobs, tests) to AI tooling and editors.

---

⚡ TL;DR Quick-start

Create a Buildkite API Token

# Run via Docker with the token from above
docker run --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx buildkite/mcp-server stdio

---

🗂️ Table of Contents

• Prerequisites
• API Token Scopes
• Installation
• Configuration & Usage
• Toolsets
• Features
• Screenshots
• Security
• Contributing
• License

---

🛠️ Prerequisites

Requirement	Notes
Docker ≥ 20.x	Recommended path – run in an isolated container
OR Go ≥ 1.24	Needed only for building natively
Buildkite API token	Create at https://buildkite.com/user/api-access-tokens
Internet access to ghcr.io	To pull the pre-built image

---

🔑 API Token Scopes

All READ and WRITE functionality

👉 Quick add: Create token with READ and WRITE functionality

Scope	Purpose
write_pipelines	Create and update pipelines
write_builds	Create builds, unblock jobs, trigger builds

Includes all READONLY and Minimum scopes listed below.

All READONLY functionality

👉 Quick add: Create token with READONLY functionality

Scope	Purpose
read_clusters	Access cluster & queue information
read_pipelines	Pipeline configuration
read_builds	Builds, jobs & annotations
read_build_logs	Job log output
read_user	Current user info
read_organizations	Organization details
read_artifacts	Build artifacts & metadata
read_suites	Buildkite Test Engine data

Includes Minimum scopes listed below.

Minimum recommended

👉 Quick add: Create token with Basic functionality

Scope	Purpose
read_builds	Builds, jobs & annotations
read_pipelines	Pipeline information
read_user	User identification

Note: Tools requiring write access, like unblock_job, create_build and create_pipeline require the "All READ and WRITE functionality" token.

---

📦 Installation

1. Docker (recommended)

docker pull buildkite/mcp-server

Run:

docker run --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx buildkite/mcp-server stdio

2. Pre-built binary

Download the latest release from GitHub Releases. Binaries are fully-static and require no libc.

If you're on macOS, you can use Homebrew:

brew install buildkite/buildkite/buildkite-mcp-server

3. Build from source

go install github.com/buildkite/buildkite-mcp-server@latest
# or
goreleaser build --snapshot --clean
# or
make build    # uses goreleaser (snapshot)

4. Docker Desktop

docker mcp server enable buildkite

View on Docker MCP Hub

---

⚙️ Configuration & Usage

Docker (recommended):

# ~/.config/amp/settings.json
{
  "amp.mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q",
        "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Local binary:

# ~/.config/amp/settings.json
{
  "amp.mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Docker (recommended):

claude mcp add buildkite -- docker run --pull=always -q --rm -i -e BUILDKITE_API_TOKEN=bkua_xxxxxxxx buildkite/mcp-server stdio

Local binary:

claude mcp add buildkite --env BUILDKITE_API_TOKEN=bkua_xxxxxxxx -- buildkite-mcp-server stdio

Docker (recommended):

{
  "mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q",
        "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Local binary:

{
  "mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Add Buildkite MCP Server to Cursor

Docker (recommended):

{
  "buildkite": {
    "command": "docker",
    "args": [
      "run", "--pull=always", "-q",
      "-i", "--rm",
      "-e", "BUILDKITE_API_TOKEN",
      "buildkite/mcp-server",
      "stdio"
    ]
  }
}

Local binary:

{
  "buildkite": {
    "command": "buildkite-mcp-server",
    "args": ["stdio"],
    "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
  }
}

Docker (recommended):

extensions:
  fetch:
    name: Buildkite
    cmd: docker
    args: ["run", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN", "buildkite/mcp-server", "stdio"]
    enabled: true
    envs: { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    type: stdio
    timeout: 300

Local binary:

extensions:
  fetch:
    name: Buildkite
    cmd: buildkite-mcp-server
    args: [stdio]
    enabled: true
    envs: { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    type: stdio
    timeout: 300

{
  "inputs": [
    {
      "id": "BUILDKITE_API_TOKEN",
      "type": "promptString",
      "description": "Enter your Buildkite Access Token",
      "password": true
    }
  ],
  "servers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", 
        "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "${input:BUILDKITE_API_TOKEN}" }
    }
  }
}

{
  "mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", 
        "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Local binary:

{
  "mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

The Buildkite MCP server is packaged and available in the Toolhive registry.

Before running the server, store your API token as a secret:

cat ~/path/to/your/buildkite-api-token.txt | thv secret set buildkite-api-key

Run the server:

thv run --secret buildkite-api-key,target=BUILDKITE_API_TOKEN buildkite

There is a Zed editor extension available in the official extension gallery. During installation it will ask for an API token which will be added to your settings.

Or you can manually configure:

// ~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-server-buildkite": {
      "settings": {
        "buildkite_api_token": "your-buildkite-token-here"
      }
    }
  }
}

---

🧰 Toolsets

The Buildkite MCP server organizes its tools into logical toolsets that can be enabled or disabled based on your needs. This allows you to control which Buildkite API functionality is available to your AI assistant.

Available Toolsets

Toolset	Description	Key Tools
clusters	Cluster Management	get_cluster, list_clusters, get_cluster_queue, list_cluster_queues
pipelines	Pipeline Management	get_pipeline, list_pipelines, create_pipeline, update_pipeline
builds	Build Operations	list_builds, get_build, create_build, wait_for_build, get_jobs, unblock_job
artifacts	Artifact Management	list_artifacts, get_artifact
logs	Log Analysis	search_logs, tail_logs, read_logs, get_logs_info
tests	Test Engine	list_test_runs, get_test_run, get_failed_executions, get_test
annotations	Annotation Management	list_annotations
user	User & Organization	current_user, user_token_organization, access_token

Configuration

Configure toolsets using environment variables or command-line flags:

Environment Variable:

export BUILDKITE_TOOLSETS="user,pipelines,builds"

Command Line:

buildkite-mcp-server stdio --enabled-toolsets="user,pipelines,builds"

Docker:

docker run --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx -e BUILDKITE_TOOLSETS="user,pipelines,builds" buildkite/mcp-server stdio

Special Values

• all - Enables all available toolsets (default)
• Read-only mode - Add --read-only flag or BUILDKITE_READ_ONLY=true to filter out write operations

Recommended Configurations

Minimum (recommended baseline):

BUILDKITE_TOOLSETS="user"

Always include the user toolset as it provides essential user and organization information that many AI workflows depend on.

CI/CD Management:

BUILDKITE_TOOLSETS="user,pipelines,builds"

Debugging & Analysis:

BUILDKITE_TOOLSETS="user,builds,logs,tests,annotations"

Full Access:

BUILDKITE_TOOLSETS="all"

Read-Only Mode

When read-only mode is enabled, tools that perform write operations (like create_build, create_pipeline, unblock_job) are automatically filtered out, leaving only safe read operations available.

# Read-only configuration
export BUILDKITE_READ_ONLY=true
export BUILDKITE_TOOLSETS="all"

This is particularly useful when you want to grant AI assistants access to query and analyze your Buildkite data without the ability to make changes.

---

🔧 Environment Variables

Variable	Description	Default	Usage
BUILDKITE_API_TOKEN	Your Buildkite API access token	Required*	Authentication for all API requests
BUILDKITE_API_TOKEN_FROM_1PASSWORD	1Password item reference for API token	-	Alternative to BUILDKITE_API_TOKEN. Format: op://vault/item/field
BUILDKITE_TOOLSETS	Comma-separated list of toolsets to enable	all	Controls which tool groups are available
BUILDKITE_READ_ONLY	Enable read-only mode (filters out write operations)	false	Security setting for AI assistants
HTTP_LISTEN_ADDR	Address for HTTP server to listen on	localhost:3000	Used with http command

*Either BUILDKITE_API_TOKEN or BUILDKITE_API_TOKEN_FROM_1PASSWORD must be specified, but not both.

---

🔐 1Password Integration

For enhanced security, you can store your Buildkite API token in 1Password and reference it using the 1Password CLI instead of exposing it as a plain environment variable.

Prerequisites

• 1Password CLI installed and authenticated
• Your Buildkite API token stored in a 1Password item

Usage

Instead of using BUILDKITE_API_TOKEN, use BUILDKITE_API_TOKEN_FROM_1PASSWORD with a 1Password item reference:

Environment Variable:

export BUILDKITE_API_TOKEN_FROM_1PASSWORD="op://Private/Buildkite API Token/credential"
buildkite-mcp-server stdio

Command Line:

buildkite-mcp-server stdio --api-token-from-1password="op://Private/Buildkite API Token/credential"

Note: The server will call op read -n <reference> to fetch the token. Ensure your 1Password CLI is properly authenticated before starting the server.

Client Configuration Examples

{
  "mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN_FROM_1PASSWORD": "op://Private/Buildkite API Token/credential"
      }
    }
  }
}

{
  "servers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN_FROM_1PASSWORD": "op://Private/Buildkite API Token/credential"
      }
    }
  }
}

---

🛠️ Tools & Features

Tool	Description
get_cluster	Get detailed information about a specific cluster including its name, description, default queue, and configuration
list_clusters	List all clusters in an organization with their names, descriptions, default queues, and creation details
get_cluster_queue	Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration
list_cluster_queues	List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration
get_pipeline	Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics
list_pipelines	List all pipelines in an organization with their basic details, build counts, and current status
create_pipeline	Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment
update_pipeline	Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata
list_builds	List all builds for a pipeline with their status, commit information, and metadata
get_build	Get detailed information about a specific build including its jobs, timing, and execution details
get_build_test_engine_runs	Get test engine runs data for a specific build in Buildkite. This can be used to look up Test Runs.
create_build	Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information
wait_for_build	Wait for a specific build to complete
current_user	Get details about the user account that owns the API token, including name, email, avatar, and account creation date
user_token_organization	Get the organization associated with the user token used for this request
get_jobs	Get all jobs for a specific build including their state, timing, commands, and execution details
unblock_job	Unblock a blocked job in a Buildkite build to allow it to continue execution
list_artifacts	List all artifacts for a build across all jobs, including file details, paths, sizes, MIME types, and download URLs
get_artifact	Get detailed information about a specific artifact including its metadata, file size, SHA-1 hash, and download URL
list_annotations	List all annotations for a build, including their context, style (success/info/warning/error), rendered HTML content, and creation timestamps
list_test_runs	List all test runs for a test suite in Buildkite Test Engine
get_test_run	Get a specific test run in Buildkite Test Engine
get_failed_executions	Get failed test executions for a specific test run in Buildkite Test Engine. Optionally get the expanded failure details such as full error messages and stack traces.
get_test	Get a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions
search_logs	Search log entries using regex patterns with optional context lines
tail_logs	Show the last N entries from the log file
get_logs_info	Get metadata and statistics about the Parquet log file
read_logs	Read log entries from the file, optionally starting from a specific row number
access_token	Get information about the current API access token including its scopes and UUID

---

🔍 Job Log Analysis Tools

Inspect Buildkite job logs in milliseconds, with full-text search, tail, and structured reads – all from one endpoint.

The server ships with four log analysis tools that convert Buildkite job output to structured Parquet data for efficient querying:

• search_logs – Regex search with context lines for debugging failures
• tail_logs – Show last N lines for recent errors and status checks
• read_logs – Stream log entries from specific positions
• get_logs_info – File metadata and statistics before reading content

Smart Caching & Storage

The first request downloads and converts logs to Parquet format; subsequent requests are zero-API calls with near-instant response times. All tools return token-efficient JSON by default for optimal AI/LLM performance.

Environment	Default Cache Location
Desktop/Laptop	file://$HOME/.bklog
Docker/K8s/CI	file:///tmp/bklog
Custom override	$BKLOG_CACHE_URL (any gocloud URL)

💡 Zero-config setup: Don't set anything for local testing—the server auto-picks the right directory. Set BKLOG_CACHE_URL to override with S3 (s3://bucket/path), GCS, Azure, or custom storage backends.

Examples:

# Local development with persistent cache
export BKLOG_CACHE_URL="file:///Users/me/bklog-cache"

# Shared cache across build agents
export BKLOG_CACHE_URL="s3://ci-logs-cache/buildkite/"

---

🌐 Streamable HTTP / SSE transport

You can also run the MCP server using the Streamable HTTP Transport, and connect to the MCP server at http://localhost:3000/mcp.

buildkite-mcp-server http --api-token=${BUILDKITE_API_TOKEN}

Or with the legacy HTTP/SSE transport, and connect to the MCP server at http://localhost:3000/sse.

buildkite-mcp-server http --use-sse --api-token=${BUILDKITE_API_TOKEN}

You can also set the listen address via environment variable:

HTTP_LISTEN_ADDR="localhost:4321" buildkite-mcp-server http

To run the server with Streamable HTTP transport in a docker and expose on port 3000.

docker run --pull=always -q --rm -e BUILDKITE_API_TOKEN -e HTTP_LISTEN_ADDR=":3000" -p 127.0.0.1:3000:3000 buildkite/mcp-server http

[!CAUTION] By default, Docker will bind published ports on all interfaces, making your MCP server accessible from any devices on your local network. We recommend using the default stdio transport when used locally, but if you must use HTTP/SSE, binding the forwarded port to 127.0.0.1, as in the example above will prevent other devices on your local network from accessing the server.

📸 Screenshots

---

🤖 AGENTS.md

We recommend adding a hint to your AGENTS.md, or equivalent agent configuration file, for example CLAUDE.md ect. This will typically be under an architecture section.

This hint will orientate the agent towards using the buildkite MCP to quickly diagnose build issues, or return project level CI/CD insights quickly. You should replace the organization, pipeline slug(s) and pipeline files based on your project.

- **CI/CD**: `buildkite` organization, `buildkite-mcp-server` pipeline slug for build and test (`.buildkite/pipeline.yml`), `buildkite-mcp-server-release` pipeline slug for releases (`.buildkite/pipeline.release.yml`)

---

📚 Library Usage

The exported Go API of this module should be considered unstable, and subject to breaking changes as we evolve this project.

---

🔒 Security

To ensure the MCP server is run in a secure environment, we recommend running it in a container.

This image is built from cgr.dev/chainguard/static and runs as an unprivileged user.

---

🤝 Contributing

Development guidelines are in DEVELOPMENT.md.

Run the test suite:

go test ./...

---

📝 License

MIT © Buildkite

SPDX-License-Identifier: MIT