Skip to main content
Glama

buildkite-mcp-server

by buildkite

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

RequirementNotes
Docker ≥ 20.xRecommended path – run in an isolated container
OR Go ≥ 1.24Needed only for building natively
Buildkite API tokenCreate at https://buildkite.com/user/api-access-tokens
Internet access to ghcr.ioTo pull the pre-built image

🔑 API Token Scopes

Full functionality

👉 Quick add: Create token with Full functionality

ScopePurpose
read_clustersAccess cluster & queue information
read_pipelinesPipeline configuration
read_buildsBuilds, jobs & annotations
read_build_logsJob log output
read_userCurrent user info
read_organizationsOrganization details
read_artifactsBuild artifacts & metadata
read_suitesBuildkite Test Engine data

👉 Quick add: Create token with Basic functionality

ScopePurpose
read_buildsBuilds, jobs & annotations
read_pipelinesPipeline information
read_userUser identification

📦 Installation

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

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

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

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

🔧 Environment Variables

VariableDescriptionDefaultUsage
BUILDKITE_API_TOKENYour Buildkite API access tokenRequiredAuthentication for all API requests

🛠️ Tools & Features

ToolDescription
get_clusterGet detailed information about a specific cluster including its name, description, default queue, and configuration
list_clustersList all clusters in an organization with their names, descriptions, default queues, and creation details
get_cluster_queueGet detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration
list_cluster_queuesList all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration
get_pipelineGet detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics
list_pipelinesList all pipelines in an organization with their basic details, build counts, and current status
create_pipelineSet up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment
update_pipelineModify an existing Buildkite pipeline's configuration, repository, settings, or metadata
list_buildsList all builds for a pipeline with their status, commit information, and metadata
get_buildGet detailed information about a specific build including its jobs, timing, and execution details
get_build_test_engine_runsGet test engine runs data for a specific build in Buildkite. This can be used to look up Test Runs.
create_buildTrigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information
current_userGet details about the user account that owns the API token, including name, email, avatar, and account creation date
user_token_organizationGet the organization associated with the user token used for this request
get_jobsGet all jobs for a specific build including their state, timing, commands, and execution details
list_artifactsList all artifacts for a build across all jobs, including file details, paths, sizes, MIME types, and download URLs
get_artifactGet detailed information about a specific artifact including its metadata, file size, SHA-1 hash, and download URL
list_annotationsList all annotations for a build, including their context, style (success/info/warning/error), rendered HTML content, and creation timestamps
list_test_runsList all test runs for a test suite in Buildkite Test Engine
get_test_runGet a specific test run in Buildkite Test Engine
get_failed_executionsGet 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_testGet a specific test in Buildkite Test Engine. This provides additional metadata for failed test executions
search_logsSearch log entries using regex patterns with optional context lines
tail_logsShow the last N entries from the log file
get_logs_infoGet metadata and statistics about the Parquet log file
read_logsRead log entries from the file, optionally starting from a specific row number
access_tokenGet 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.

EnvironmentDefault Cache Location
Desktop/Laptopfile://$HOME/.bklog
Docker/K8s/CIfile:///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 --listen "localhost:3000" --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 --listen "localhost:3000" --use-sse --api-token=${BUILDKITE_API_TOKEN}

📸 Screenshots

Get Pipeline Tool


🤖 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

Related MCP Servers

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/buildkite/buildkite-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server