Model Context Protocol (MCP) server exposing Buildkite data (pipelines, builds, jobs, tests) to AI tooling and editors.
# 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
- Prerequisites
- API Token Scopes
- Installation
- Configuration & Usage
- Features
- Screenshots
- Security
- Contributing
- License
| 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 |
👉 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 |
👉 Quick add: Create token with Basic functionality
| Scope | Purpose |
|---|---|
read_builds |
Builds, jobs & annotations |
read_pipelines |
Pipeline information |
read_user |
User identification |
docker pull ghcr.io/buildkite/buildkite-mcp-serverRun:
docker run -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx ghcr.io/buildkite/buildkite-mcp-server stdioDownload 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-servergo install github.com/buildkite/buildkite-mcp-server@latest
# or
goreleaser build --snapshot --clean
# or
make build # uses goreleaser (snapshot)
docker mcp server enable buildkiteView on Docker MCP Hub
Amp
Docker (recommended):
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 }
}
}
}Claude Code
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
Claude Desktop
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 }
}
}
}Goose
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: 300Local 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: 300VS Code
{
"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}" }
}
}
}Windsurf
{
"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 }
}
}
}Zed
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"
}
}
}
}| 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 |
The JOB_LOG_TOKEN_THRESHOLD environment variable controls when large job logs are downloaded to your local temporary directory instead of being returned directly.
- 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
| 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 |
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.
Development guidelines are in DEVELOPMENT.md.
Run the test suite:
go test ./...MIT © Buildkite
SPDX-License-Identifier: MIT
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
# ~/.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" } } } }