access_tokenLABSCO SUMMARY
The log tools are what make this worth wiring up: CI logs arrive searchable instead of as a wall of text.
Buildkite converts job logs into a queryable form, so an agent can grep for the error with context lines or tail the last entries rather than pulling megabytes into the conversation. Everything needed to close the loop is in the same server — find the failing job, read the annotation, retry it — and token scopes stay the real boundary, with a read-only endpoint if you would rather nothing can be triggered at all.
What it is
Buildkite's own server over its REST API, covering pipelines, builds, jobs, logs, artifacts, annotations, clusters, agents and Test Engine.
What you get
- Builds listed for an organization or a pipeline as lightweight summaries, with a build's detail, its jobs filtered by state, and any single job by UUID
- Job logs made searchable rather than dumped: regex search with context lines, a tail of the last entries, and reads from a given row
- Recovery actions in the same place as the diagnosis — retry a job, unblock a blocked job, cancel or rebuild a build, or create a new one on a commit and branch
- Pipelines created and updated from YAML, and pipeline schedules read, created and updated with their cron expression, branch and enabled state
- Artifacts across a build or one job, with paths, sizes, MIME types and download URLs, and artifact content fetched base64-encoded
- Annotations listed for a build or job, and new ones created
- Test Engine data: tests in a suite with execution metrics over a time range, a single test's metadata for failed executions, and the runs for a suite
- Clusters and queues managed end to end, including pausing and resuming dispatch on a queue
- Agents inspected with their connection state, host, version, current job and pause status
- Responses trimmed to a subset of REST fields on purpose, to keep noise and token cost down
Requirements
A Buildkite account. The recommended path is the remote server Buildkite hosts at https://mcp.buildkite.com/mcp, which issues a short-lived OAuth token for your user with read and write scopes; https://mcp.buildkite.com/mcp/readonly is the read-only equivalent, and https://mcp.buildkite.com/direct takes a Buildkite API token in an Authorization header for headless agents that cannot complete OAuth. To run it yourself, use the container image ghcr.io/buildkite/buildkite-mcp-server with BUILDKITE_API_TOKEN — each tool needs a matching token scope, such as read_builds or write_pipelines. Toolsets restrict which categories are exposed at all.
Setup effort
Add the hosted endpoint — paste it into your client
USE CASES
Finding out why the build broke
List the jobs for the build, then search that job's log for the error with surrounding context.
Getting a stuck pipeline moving again
Unblock the blocked job, or retry the one that failed on something transient.
Chasing a flaky test rather than a broken build
Read the Test Engine runs for the build, then the test's metrics and its failed-execution metadata.
Retrieving what a build produced
List the artifacts for the build or a single job, then download the one you need.
Setting up or adjusting a pipeline
Create it from YAML with its repository and cluster, then add or amend the schedule that triggers it.
Working out why nothing is being dispatched
Check the agents' connection state and current jobs, then the queue's dispatch status — and resume it if it was paused.
47 tools
Listed in project docs. Your client may show a different list.
current_useruser_token_organizationlist_clustersget_clustercreate_clusterupdate_clusterlist_cluster_queuesget_cluster_queuecreate_cluster_queueupdate_cluster_queuepause_cluster_queue_dispatchresume_cluster_queue_dispatchlist_agentsget_agentlist_pipelinesget_pipelinecreate_pipelineupdate_pipelinelist_pipeline_schedulesget_pipeline_schedulecreate_pipeline_scheduleupdate_pipeline_schedulelist_buildsget_buildget_build_test_engine_runscreate_buildcancel_buildrebuild_buildlist_jobsget_jobunblock_jobretry_jobget_job_envsearch_logstail_logsread_logslist_artifacts_for_buildlist_artifacts_for_jobget_artifactlist_annotationscreate_annotationlist_testsget_testlist_test_runsget_test_runget_failed_executionsBEFORE YOU INSTALL
What to know first
Tools you get
47 tools named in the project's documentation. The read-only endpoint https://mcp.buildkite.com/mcp/readonly drops every create, update, cancel, retry, unblock, rebuild and pause/resume tool, and any tool fails if your token lacks its scope. Names like read_builds are token scopes, not tools.
Optional
BUILDKITE_API_TOKEN in your environment
Where it runs
All 3 documented setups connect to a hosted endpoint.
INSTALLATION
Connect your client
Server setup
Setup
RECOMMENDED (no install): use the hosted remote MCP server. Add https://mcp.buildkite.com/mcp to your AI tool and complete the OAuth sign-in — no API token needed; Buildkite issues a short-lived OAuth access token (valid 12 hours, refresh token 7 days) with read and write scopes.
Read-only variant of the same hosted server:
https://mcp.buildkite.com/mcp/readonlyFor headless agents that cannot complete interactive OAuth: use https://mcp.buildkite.com/direct and send Authorization: Bearer <YOUR_BUILDKITE_API_TOKEN>.
To run the server locally instead, create a Buildkite API access token (it usually begins with bkua_) and start the Docker image, which is Buildkite's recommended local method:
docker run --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=<YOUR_BUILDKITE_API_TOKEN> buildkite/mcp-server stdioOn macOS you can install the binary with Homebrew instead:
brew install buildkite/buildkite/buildkite-mcp-serverSelf-hosted HTTP mode (already-installed binary): BUILDKITE_API_TOKEN=<YOUR_BUILDKITE_API_TOKEN> buildkite-mcp-server http --passthrough-http-header X-User-Identity — or, to make every request carry its own token, BUILDKITE_PASSTHROUGH_HTTP_HEADERS=Authorization buildkite-mcp-server http with no process-wide token.
Hosted endpoint
https://mcp.buildkite.com/mcpAdd this hosted endpoint to your MCP client.
MCP Clients
Any MCP client — OAuth
{
"mcpServers": {
"buildkite-mcp-server": {
"url": "https://mcp.buildkite.com/mcp"
}
}
}Any MCP client — API token
{
"mcpServers": {
"buildkite-mcp-server": {
"url": "https://mcp.buildkite.com/direct",
"headers": {
"Authorization": "Bearer <YOUR_BUILDKITE_API_TOKEN>"
}
}
}
}Any MCP client — read-only
{
"mcpServers": {
"buildkite-mcp-server": {
"url": "https://mcp.buildkite.com/mcp/readonly"
}
}
}