Installing the Buildkite MCP server

The Buildkite MCP server is available both locally and remotely. This page is about installing and configuring the local MCP server, beginning with Before you start.

Once you have installed your local Buildkite MCP server using the relevant instructions on this page, you can proceed to configure your AI tools or agents to work with this MCP server.

Buildkite's remote MCP server requires no installation and is available publicly, with authentication and authorization fully managed by OAuth. If you're working directly with an AI tool as opposed to using an AI agent in a workflow (see Types of MCP servers for more information), and you'd prefer to use the remote MCP server instead, proceed directly to its Configuring AI tools page.

Before you start

To use Buildkite's MCP server locally, you'll need the following:

A Buildkite user account, which you can sign into your Buildkite organization with.
A Buildkite API access token for this Buildkite user account. Learn more about the required scopes to configure for this token in Configure an API access token.

Specific requirements for each type of local installation method for the Buildkite MCP server are covered in their relevant installation sections.

Configure an API access token

This section explains which scopes your local Buildkite MCP server's API access token requires permission for within your Buildkite organization, for your particular use case. These scopes typically fit into the following categories:

Minimum access
All read-only access
All read and write access

Minimum access

For minimum access, select the following scopes for your local MCP server's API access token. These scopes provide your token with the minimum required access permissions on the Buildkite MCP server, and prevent access to more sensitive information within your Buildkite organization.

Scope		Access permissions
Read Builds	`read_builds`	List and retrieve details of a pipeline's builds, jobs and annotations.
Read Pipelines	`read_pipelines`	List and retrieve details of pipelines themselves.
Read User	`read_user`	Retrieve basic details about a Buildkite user account.

You can also create a new Buildkite API access token rapidly with these pre-selected scopes.

All read-only access

For all read-only access, select both the minimum access permissions, as well as the following additional scopes for your local MCP server's API access token. These scopes provide your token with all read-only access permissions available through the Buildkite MCP server. These additional scopes include permission to access more information about your Buildkite organization, including clusters, more pipeline build details (that is, log information), as well as access to Test Engine test suite data.

Scope		Access permissions
Read Clusters	`read_clusters`	List and retrieve details of clusters and their queues.
Read Artifacts	`read_artifacts`	Retrieve build artifacts and their metadata.
Read Build Logs	`read_build_logs`	Retrieve the log output of builds and their jobs.
Read Organizations	`read_organizations`	List and retrieve details of the Buildkite organization.
Read Suites	`read_suites`	List and retrieve details of Test Engine test suites—including runs, tests, executions, etc.

You can also create a new Buildkite API access token rapidly with these pre-selected scopes.

All read and write access

For all read and write access, select both the minimum access permissions and all read-only access permissions, as well as the following additional scopes for your local MCP server's API access token. These scopes provide your token with all available read and write access permissions available through the Buildkite MCP server. These additional scopes include permission to edit pipelines and their builds within your Buildkite organization.

Scope		Access permissions
Write Builds	`write_builds`	Create new pipeline builds, unblock jobs, and trigger builds.
Write Pipelines	`write_pipelines`	Create new pipelines, update update existing ones, and delete pipelines too.

You can also create a new Buildkite API access token rapidly with these pre-selected scopes.

Install and run the server locally

To install and run the Buildkite MCP server locally, you can do so using Docker (recommended), natively as a pre-built binary, or build it from source.

Using Docker

To run the Buildkite MCP server locally in Docker:

Ensure you have installed and are running Docker version 20.x or later.

Note:
- You can also confirm the minimum required Docker version from the buildkite-mcp-server's README.
- These remaining steps are for running the MCP server in Docker from the command line, or if you have installed the Docker Engine only. If you've installed Docker through Docker Desktop, you can follow the more convenient Docker Desktop instructions instead.
Open a terminal or command prompt, and run this command to obtain the Buildkite MCP server Docker image.
```
docker pull buildkite/mcp-server
```
Run the following command to spin up the Buildkite MCP server image in Docker.
```
docker run --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=<api-token-value> buildkite/mcp-server stdio
```
where <api-token-value> is the value of your Buildkite API access token, set with your required scopes. This token usually begins with the value bkua_.

Using Docker Desktop

If you are using Docker Desktop, you can add the Buildkite MCP server to the MCP Toolkit area of Docker Desktop.

To do so, visit the Buildkite MCP server page on Docker's mcp hub site for MCP servers. This page provides details on which Docker Desktop versions are supported, and a button from which you can add the MCP server directly to your Docker Desktop installation.

Using a pre-built binary

To run the Buildkite MCP server locally using a pre-built binary, follow these steps, bearing in mind that macOS users can also use the convenient Homebrew method as an alternative to this procedure:

Visit the buildkite-mcp-server Releases page in GitHub.
Download the appropriate pre-built binary file for your particular operating system and its architecture. For macOS, choose the appropriate Darwin binary for your machine's architecture.
Extract the binary and execute it to install the Buildkite MCP server locally to your computer.

The installer is fully static, and no pre-requisite libraries are required.

Homebrew method

Instead of installing the relevant Darwin binary from the buildkite-mcp-server Releases page, you can run this Homebrew command to install the Buildkite MCP server locally on macOS:

brew install buildkite/buildkite/buildkite-mcp-server

Building from source

To build the Buildkite MCP server locally from source, run these commands:

Ensure you have installed Go version 1.24 or later.

Note: You can also confirm the minimum required Go version from the buildkite-mcp-server's README.

Run the following commands to build the MCP server locally from source.

go install github.com/buildkite/buildkite-mcp-server/cmd/buildkite-mcp-server@latest

If you're interested in contributing to the development of the Buildkite MCP server, see the Contributing section of the README and Development guide for more information.

Self-hosting the MCP server

You can install the Buildkite MCP server as your own self-hosted server, which effectively behaves similarly to Buildkite's remote MCP server, but as one that operates in your own environment.

To do this, use the following the following command, which runs the MCP server with streamable HTTP transport, and makes the server available through http://localhost:3000/mcp:

buildkite-mcp-server http --api-token=${BUILDKITE_API_TOKEN}

where ${BUILDKITE_API_TOKEN} is the value of your configured Buildkite API access token, set with your required scopes.

To run the MCP server with legacy HTTP or server-sent events (SSE), use this command with the --use-sse option. For example:

buildkite-mcp-server http --use-sse --api-token=${BUILDKITE_API_TOKEN}

To change the listening address or port on which the MCP server runs, use the HTTP_LISTEN_ADDR environment variable. For example, to set this port to 4321:

HTTP_LISTEN_ADDR="localhost:4321" buildkite-mcp-server http --api-token=...

To run the MCP server using Docker with streamable HTTP transport and expose the server through port 3000:

docker run --pull=always -q --rm -e BUILDKITE_API_TOKEN -e HTTP_LISTEN_ADDR=":3000" -p 127.0.0.1:3000:3000 buildkite/mcp-server http

With your self-hosted MCP server up and running, you can now configure your AI tools as you would for Buildkite's remote MCP server, but substituting its URL (https://mcp.buildkite.com/mcp) for the URL of your self-hosted MCP server (for example, http://127.0.0.1:3000/mcp). Note that the OAuth authentication flow won't be triggered in this case, as your server will be configured to use your own API access token.