What is Buildkite?

Buildkite is an MCP (Model Context Protocol) server designed for effective pipeline and build management within Buildkite, a popular CI/CD platform. This server simplifies accessing information about clusters, pipelines, builds, jobs, artifacts, and test runs in Buildkite from various tools and IDEs like Claude Desktop, GitHub Copilot, and other editors through the MCP.

How to use Buildkite?

1. Set up the Buildkite MCP server by running it as a Docker container or building it manually.
2. Configure your API token with the necessary scopes to access Buildkite data.
3. Integrate the server with your preferred tools such as Claude Desktop, VSCode, Zed, or others by adding the server configuration in the respective settings.
4. Use the provided tools (e.g., list_pipelines, get_build, get_artifacts) to interact with Buildkite data. For example, use get_pipeline to retrieve detailed pipeline information.
5. Access logs, annotations, test runs, and other details as needed to streamline your CI/CD workflow.

Key features of Buildkite?

• Cluster and Queue Management: Get and list clusters and queues with details on configurations and statuses.
• Pipeline Administration: Create, update, and retrieve pipeline configurations including triggers and execution details.
• Build Inspection: List and get detailed information about builds, including jobs, logs, timing, and execution specifics.
• Artifact Access: Retrieve all build artifacts, including file details, download URLs, and metadata.
• Test Management: Access test runs, get failed executions, and retrieve test-specific metadata.
• User and Organization Data: Obtain current user details and organization information.
• Security and Configuration: Run securely in a container, configure with API token scopes, and integrate with various tools.

Use cases of Buildkite?

1. Continuous Integration Monitoring: Use list_builds and get_build to track the status of ongoing and completed builds, ensuring pipeline health.
2. Pipeline Debugging: Retrieve logs and details of failed jobs (get_job_logs) to diagnose and fix issues.
3. Artifact Management: List and download artifacts (list_artifacts, get_artifact) for builds to deploy or analyze results.
4. Test Analysis: Access detailed test runs to understand failures and improve test quality.
5. Collaborative Development: Share pipeline and build information across teams and tools to streamline collaboration.

FAQ from Buildkite?

• What API token scopes are required?

  For full functionality, scopes like read_clusters, read_pipelines, read_builds, read_build_logs, read_user, read_organizations, read_artifacts, and read_suites are needed. You can find detailed guidance here.

• How secure is the container deployment?

  The container image is built on the secure cgr.dev/chainguard/static base image and runs the MCP server as a non-root user.

• Can I use Buildkite without Docker?

  Yes, you can build and run the server locally. Use goreleaser build --snapshot --clean to get the binary.

• Which tools and IDEs support Buildkite?

  Buildkite integrates with Claude Desktop, Goose, VSCode, Zed, GitHub Copilot, and more.

• Where can I find help or report issues?

  Check the DEVELOPMENT.md for development notes or contribute through the GitHub repository linked in the project.

buildkite-mcp-server

This is an Model Context Protocol (MCP) server for Buildkite. The goal is to provide access to information from buildkite about pipelines, builds and jobs to tools such as Claude Desktop, GitHub Copilot and other tools, or editors.

Tools

• 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
• 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
• get_job_logs - Get the log output and metadata for a specific job, including content, size, and header timestamps
• 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
• access_token - Get information about the current API access token including its scopes and UUID

Example of the get_pipeline tool in action.

Production

To ensure the MCP server is run in a secure environment, we recommend running it in a container.

Pull the pre-built image (recommended):

docker pull ghcr.io/buildkite/buildkite-mcp-server

Or build it yourself using GoReleaser and copy the binary into your path:

goreleaser build --snapshot --clean

API Token Scopes

Your Buildkite API access token requires the following scopes for the MCP server to function properly:

Required Scopes

For full functionality with all available tools, your API token needs these scopes:

• read_clusters - Access cluster and queue information
• read_pipelines - Access pipeline details and configurations
• read_builds - Access builds, jobs, and annotations
• read_build_logs - Access job log output
• read_user - Access current user information
• read_organizations - Access organization details
• read_artifacts - Access build artifacts and metadata
• read_suites - Access Test Engine data (if using Test Engine)

Create a buildkite API token with Full functionality

Minimum Recommended Scopes

For basic CI/CD monitoring and inspection, these core scopes provide the most commonly used functionality:

• read_builds - Covers builds, jobs, and annotations
• read_pipelines - Pipeline information
• read_user - User identification

Create a buildkite API token with Basic functionality (minimum scopes)

Configuration

To get started with various tools select one of the following.

Claude Desktop ## Claude Desktop Use this configuration if you want to run the server buildkite-mcp-server Docker (recommended): json { "mcpServers": { "buildkite": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN", "ghcr.io/buildkite/buildkite-mcp-server", "stdio" ], "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" } } } } Configuration if you have buildkite-mcp-server installed locally. json { "mcpServers": { "buildkite": { "command": "buildkite-mcp-server", "args": [ "stdio" ], "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" } } } }

Goose ## Goose For Docker with Goose (recommended): yaml extensions: fetch: name: Buildkite cmd: docker args: ["run", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN", "ghcr.io/buildkite/buildkite-mcp-server", "stdio"] enabled: true envs: { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" } type: stdio timeout: 300 Local configuration for Goose: yaml extensions: fetch: name: Buildkite cmd: buildkite-mcp-server args: [stdio] enabled: true envs: { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx" } type: stdio timeout: 300

VSCode ## VSCode VSCode supports interactive inputs for variables. To get the API token interactively on MCP startup, put the following in .vscode/mcp.json json { "inputs": [ { "id": "BUILDKITE_API_TOKEN", "type": "promptString", "description": "Enter your BuildKite Access Token (https://buildkite.com/user/api-access-tokens)", "password": true } ], "servers": { "buildkite": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN", "ghcr.io/buildkite/buildkite-mcp-server", "stdio" ], "env": { "BUILDKITE_API_TOKEN": "${input:BUILDKITE_API_TOKEN}" } } } }

Zed ## Zed 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: jsonc // ~/.config/zed/settings.json { "context_servers": { "mcp-server-buildkite": { "settings": { "buildkite_api_token": "your-buildkite-token-here", } } } }

---

Security

This container image is built using cgr.dev/chainguard/static base image and is configured to run the MCP server as a non-root user.

Contributing

Notes on building this project are in the DEVELOPMENT.md

License

This project is released under MIT license.