How to connect Buildkite MCP with Python

Get information about the current API access token including its scopes and UUID

Cancel a running build on a Buildkite pipeline

Create an annotation on a build or specific job. Use scope='build' (default) or scope='job' with job_id

Trigger a new build on a Buildkite pipeline for a specific commit and branch, with optional environment variables, metadata, and author information

Create a new cluster in an organization

Create a new queue in a cluster

Create cluster secret

Set up a new CI/CD pipeline in Buildkite with YAML configuration, repository connection, and cluster assignment

Create a new pipeline schedule that triggers builds on a cron-driven interval

Get details about the user account that owns the API token, including name, email, avatar, and account creation date

Get detailed information about a specific agent including its connection state, host details, current job, metadata, and pause status

Get a specific artifact by organization, pipeline, build, job, and artifact identifiers. Text artifacts under 64 KiB are returned inline in `content`; larger or binary artifacts return metadata plus a short-lived `download_url`. When `download_url_auth` is "none" the URL is presigned (a buildkiteartifacts.com S3 link) — fetch it with a plain GET and NO Authorization header. It expires after `download_url_expires_in_seconds`; if it has expired, call this tool again for a fresh URL.

Get a single build with lightweight annotation summaries. Annotation bodies and jobs are not included — use list_annotations to read annotations, list_jobs or get_job for job detail, and list_step_uploads to see the dynamic pipeline configuration the build received via `buildkite-agent pipeline upload`

Diagnose a Buildkite build failure in one call. Returns build.state, build.job_state_counts tallying every job in the build by state (when present, use it to confirm the returned problem jobs are the build's only problems without calling list_jobs), terminal problem jobs, downstream failed or broken jobs, promised failures from running jobs, and size-bounded diagnostic content from logs, annotations, and failed Test Engine executions. Annotation content is in the body_html field; there is no body field. Start with this tool before calling individual job, log, annotation, or test tools.

Get test engine runs data for a specific build in Buildkite. This can be used to look up Test Runs.

Get detailed information about a specific cluster including its name, description, default queue, and configuration

Get detailed information about a specific queue including its key, description, dispatch status, and hosted agent configuration

Get cluster secret information

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 a single job by its UUID. Provide 'pipeline_slug' and 'build_number' for a build-scoped lookup, or omit both to look the job up by organization and job ID alone

Get the environment variables for a specific job in a Buildkite build

Get detailed information about a specific pipeline including its configuration, steps, environment variables, and build statistics

Get detailed information about a single pipeline schedule including its cron expression, target branch, environment variables, enabled state, last failure, and next build time

Get a single dynamic pipeline upload including its pipeline definition rendered as YAML (definition_yaml). Definitions over the API's render limit are omitted: definition_yaml is omitted, definition_yaml_omitted is true and definition_bytes reports the size. Only available while the build is within its maximum lifetime (~30 days); older builds return 410 Gone

Get a specific test in Buildkite Test Engine, including execution metrics aggregated over a selected time window. This provides additional metadata for failed test executions.

Get a specific test run in Buildkite Test Engine

List agents in an organization with their connection state, host details, version, current job, and pause status

List annotations for a build or a specific job. Use scope='build' (default) or scope='job' with job_id. Annotation content is in the body_html field; there is no body field

List all artifacts for a build across all jobs, including filenames, paths, sizes, and MIME types. Output can be large for big builds — use per_page and paginate. To fetch an artifact's contents or a download URL, call get_artifact with that artifact's id and job_id.

List all artifacts for an individual job, including filenames, paths, sizes, and MIME types. To fetch an artifact's contents or a download URL, call get_artifact with that artifact's id and job_id.

List builds for a pipeline or across all pipelines in an organization, returning a lightweight summary of each build. When pipeline_slug is omitted, lists builds across all pipelines in the organization. Jobs are not included — use list_jobs or get_job for job detail

List all queues in a cluster with their keys, descriptions, dispatch status, and agent configuration

List cluster secrets

List all clusters in an organization with their names, descriptions, default queues, and creation details

List jobs for a Buildkite build, returning an actionable summary by default. For CI failure diagnosis, use state='failed,broken' to avoid returning successful jobs. Use detail_level='detailed' for execution metadata or 'full' for the existing full MCP job response. Returns 'items' and cursor pagination 'links'

List the pipeline schedules for a pipeline, including cron expression, target branch, environment variables, enabled state, and next scheduled build time

List all pipelines in an organization with their basic details, build counts, and current status

List available skill guides that document usage patterns, pitfalls, and workflows for Buildkite MCP tools

List the dynamic pipeline uploads (`buildkite-agent pipeline upload`) a build received, newest first, without their definitions. Each item includes state, the uploading job (source_job_id), created_jobs_count (omitted until applied, 0 when applied but no jobs were created), and rejection details. Use get_step_upload to read an upload's pipeline definition. Only available while the build is within its maximum lifetime (~30 days); older builds return 410 Gone

List all test runs for a test suite in Buildkite Test Engine

List the Buildkite Test Engine suites that have recorded at least one run attributed to a pipeline, ordered by creation time. Use this to find the test_suite_slug needed by the other Test Engine tools.

List tests in a Buildkite Test Engine suite with execution metrics aggregated over a selected time window. Supports filtering, metric sorting, and pagination.

List tests and their execution metrics for a Buildkite build. Requires the build UUID (the build ID, not the pipeline build number) and supports filtering, metric sorting, and pagination.

Load the full content of a skill guide by name

Pause dispatch on a cluster queue, preventing new jobs from being dispatched to agents

Read log entries from the file, optionally starting from a specific row number. ALWAYS use 'limit' parameter to avoid excessive tokens. For recent failures, use 'tail_logs' instead. Recommended limits: investigation (100-500), exploration (use seek + small limits). The json format: {ts: timestamp_ms, c: content, rn: row_number}.

Rebuild/retry an entire build on a Buildkite pipeline

Resume dispatch on a paused cluster queue, allowing jobs to be dispatched to agents again

Retry a specific failed or timed out job in a Buildkite build

Search log entries using regex patterns with optional context lines. For recent failures, try 'tail_logs' first, then use search_logs with patterns like 'error|failed|exception' and limit: 10-20. The json format: {ts: timestamp_ms, c: content, rn: row_number}.

Show the last N entries from the log file. RECOMMENDED for failure diagnosis - most build failures appear in the final log entries. More token-efficient than read_logs for recent issues. The json format: {ts: timestamp_ms, c: content, rn: row_number}.

Unblock a blocked job in a Buildkite build to allow it to continue execution

Update an existing cluster's name, description, emoji, color, or default queue

Update an existing cluster queue's description or retry agent affinity

Modify an existing Buildkite pipeline's configuration, repository, settings, or metadata

Modify an existing pipeline schedule's cron expression, branch, environment variables, or enabled state

Get the organization associated with the user token used for this request

Wait for a build to reach a terminal state (passed, failed, canceled, skipped, not_run, or blocked on a block step), polling for up to 45 seconds. Returns finished=true along with the build once it settles. If the build is still in progress when the window closes it returns finished=false and the current state only, with no build detail — call this tool again to keep waiting. Judge a long build by build_elapsed_seconds, which counts from the build's own start time and does not reset between calls; waited_seconds covers only the latest call. Do not wait indefinitely: after roughly ten consecutive calls, stop and report the build as still running with its elapsed time rather than continuing to poll. Jobs and annotation bodies are never included — use list_jobs or get_job for job detail, and list_annotations to read annotations