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 --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx 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.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 |
👉 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.
👉 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.
👉 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_buildandcreate_pipelinerequire the "All READ and WRITE functionality" token.
docker pull buildkite/mcp-serverRun:
docker run --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx 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 --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
Claude Desktop
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, 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" }
}
}
}Cursor
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" }
}
}Optional (Local binary with Job Log Token Threshold):
{
"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", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN", "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", "--pull=always", "-q",
"-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
"buildkite/mcp-server", "stdio"
],
"env": { "BUILDKITE_API_TOKEN": "${input:BUILDKITE_API_TOKEN}" }
}
}
}Windsurf
{
"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, 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" }
}
}
}Toolhive
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-keyRun the server:
thv run --secret buildkite-api-key,target=BUILDKITE_API_TOKEN buildkiteZed
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 |
HTTP_LISTEN_ADDR |
Address for HTTP server to listen on | localhost:3000 |
Used with http command |
| 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 |
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 failurestail_logs– Show last N lines for recent errors and status checksread_logs– Stream log entries from specific positionsget_logs_info– File metadata and statistics before reading content
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_URLto 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/"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 httpTo 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 httpCaution
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.
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`)
The exported Go API of this module should be considered unstable, and subject to breaking changes as we evolve this project.
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
# ~/.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" } } } }