buildkite-mcp-server

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 -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx ghcr.io/buildkite/buildkite-mcp-server stdio

🗂️ Table of Contents

🛠️ Prerequisites

Requirement	Notes
Docker ≥ 20.x	Recommended path – run in an isolated container
OR Go ≥ 1.22	Needed only for building/running 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

Full functionality

👉 Quick add: Create token with Full 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

Minimum recommended

👉 Quick add: Create token with Basic functionality

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

📦 Installation

1. Docker (recommended)

docker pull ghcr.io/buildkite/buildkite-mcp-server

Run:

docker run -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx ghcr.io/buildkite/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", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "ghcr.io/buildkite/buildkite-mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Local binary, with the Job Log Token Threshold flag enabled:

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

Docker (recommended):

claude mcp add buildkite -- docker run --rm -i -e BUILDKITE_API_TOKEN=bkua_xxxxxxxx ghcr.io/buildkite/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", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "ghcr.io/buildkite/buildkite-mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Local binary, with the Job Log Token Threshold flag enabled:

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

Docker (recommended):

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

Local binary, with the Job Log Token Threshold flag enabled:

extensions:
  fetch:
    name: Buildkite
    cmd: buildkite-mcp-server
    args: [stdio]
    enabled: true
    envs: { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx", "JOB_LOG_TOKEN_THRESHOLD": 2000 }
    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", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "ghcr.io/buildkite/buildkite-mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "${input:BUILDKITE_API_TOKEN}" }
    }
  }
}

{
  "mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "ghcr.io/buildkite/buildkite-mcp-server", "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" }
    }
  }
}

Local binary, with the Job Log Token Threshold flag enabled:

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

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

🔧 Environment Variables

Variable	Description	Default	Usage
`BUILDKITE_API_TOKEN`	Your Buildkite API access token	Required	Authentication for all API requests
`JOB_LOG_TOKEN_THRESHOLD`	Token threshold for job logs	`0` (disabled)	Local installations only - Downloads logs to temp directory when exceeded

Job Log Token Threshold

The JOB_LOG_TOKEN_THRESHOLD environment variable controls when large job logs are downloaded to your local temporary directory instead of being returned directly.

⚠️ Important: This setting should only be used with local installations as it:

Downloads job logs to your system's temporary directory
Reads log files from disk instead of returning them in the response
May consume local disk space for large log files

When the threshold is exceeded, the get_job_logs tool will:

Download the log content to a temporary file
Return the file path and metadata instead of raw log content
Include the reason for file-based delivery in the response

🛠️ 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
`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
`get_job_logs`	Get the log output and metadata for a specific job, including content, size, and header timestamps
`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
`access_token`	Get information about the current API access token including its scopes and UUID

📸 Screenshots

Get Pipeline Tool

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

SPDX-License-Identifier: MIT

buildkite-mcp-server