Buildkite MCP Server

What buildkite/buildkite-mcp-server does

Buildkite data becomes available to MCP-compatible clients through tools for pipelines, builds, jobs, tests, and logs. The server covers both investigation and operational workflows: agents can inspect failures, compare a build with an earlier baseline, search or read logs, retry jobs, create or update pipelines, trigger builds, and examine Test Engine workflows.

The available surface is organized into toolsets. The retries toolset is designed for failure investigation and selective retries with narrower permissions than general build mutation. The investigations toolset includes the read-only compare_builds operation, while tests provides read-only access to configured Test Engine workflows.

How it works

The server communicates with clients through MCP and accesses Buildkite through its API. A stdio invocation can restrict the exposed tools with a command such as:

buildkite-mcp-server stdio --enabled-toolsets retries

Tool selection affects which operations are available, but it does not expand the scopes assigned to an existing credential. Retry workflows require read_builds, read_build_logs, and retry_builds; the Buildkite API must also have the retry feature enabled for the token owner. General build mutations in the builds or all toolsets require write_builds.

Read-only mode excludes mutating operations. This includes individual and failed-job retries, pipeline webhook-processing changes, and other build or pipeline mutations. Toolsets can also be disabled, including tools that overlap with another toolset.

Setup and configuration

Start the executable with the stdio subcommand and choose the toolsets appropriate for the client and permissions. For retry-only access, --enabled-toolsets retries exposes build and log inspection together with retry operations without requiring broad build-write access. Use dry-run support on retry_failed_jobs to review infrastructure-failure retries before applying them.

For pipeline configuration, create and update operations support GitHub provider settings, branch filters, and pipeline template UUIDs. A create request uses either nonblank configuration or an approved template UUID, not both. Updates can retain, assign, or remove a template assignment. GitHub Actions settings do not provision a dedicated Actions trigger or webhook.

Tools and capabilities

• Inspect builds, jobs, and logs with operations including list_builds, get_build, wait_for_build, list_jobs, get_job, search_logs, tail_logs, and read_logs.
• Retry a specific job or infrastructure failures with retry_job and retry_failed_jobs.
• Compare a target build with a selected or automatically discovered baseline using compare_builds.
• Create and update pipelines, trigger builds, and manage supported pipeline operations.
• Inspect and change traditional GitHub webhook processing for eligible pipelines.
• List and inspect Test Engine workflows with list_test_workflows and get_test_workflow.

Comparison results identify matched job changes, outcome counts, timing details, retry counts, and selected failure logs. The comparison distinguishes soft-failure state changes from newly blocking failures and marks unfinished builds as changing snapshots.

Limitations and notes

compare_builds searches at most 500 baseline candidates and handles inventories of up to 1,000 jobs per build. It compares final attempts rather than total wall-clock duration or retry cost. Heuristic name matching is used only for certain unkeyed jobs, and duplicate or unnamed identities may remain unmatched.

Retry operations do not include create, rebuild, cancel, or unblock actions in the retries toolset. GitHub webhook-processing controls apply only to eligible GitHub or GitHub Enterprise pipelines and require the relevant organization enrollment and permissions. They manage traditional webhook processing, not repository webhook deletion or dedicated GitHub Actions triggers.