Configuring AI tools with the local MCP server

Once you followed the required instructions on Installing the Buildkite MCP server to install the MCP server locally for your AI tool or agent, you can then use the instructions on this page to configure your AI tool or agent to work with this local Buildkite MCP server.

All the Docker instructions on this page implement the --pull=always option to ensure that the latest MCP server version is obtained when the container is started. If you are installing the Buildkite MCP server locally as a binary, then you are responsible for manually upgrading it.

The Buildkite MCP server is available both locally and remotely. This page is about configuring AI tools with the local MCP server. If you are working directly with an AI tool and would prefer it to use the remote MCP server, proceed with the relevant instructions on its Configuring AI tools page.

Amp

You can configure your Amp AI tool or agent to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, add the relevant configuration to your Amp settings.json file.

Docker

When using Docker to run the MCP server, add the following JSON configuration to your Amp settings.json file.

{
  "amp.mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server",
        "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxx" }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Binary

When using a pre-built or source-built binary to run the MCP server, add the following JSON configuration to your Amp settings.json file.

{
  "amp.mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx"
      }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Claude Code

You can configure your Claude Code AI tool or agent to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, run the relevant Claude Code command, after installing Claude Code.

Docker

When using Docker to run the MCP server, run the following Claude Code command.

claude mcp add buildkite -- docker run --pull=always -q --rm -i -e BUILDKITE_API_TOKEN=bkua_xxxxx buildkite/mcp-server stdio

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Binary

When using a pre-built or source-built binary to run the MCP server, run the following Claude Code command.

claude mcp add buildkite --env BUILDKITE_API_TOKEN=bkua_xxxxx -- buildkite-mcp-server stdio

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Claude Desktop

You can configure Claude Desktop to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, add the relevant configuration to your Claude Desktop's claude_desktop_config.json file.

Docker

When using Docker to run the MCP server, add the following configuration to your Claude Desktop's claude_desktop_config.json file, which you can access from Claude Desktop's Settings > Developer > Edit Config button on the Local MCP servers page.

{
  "mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server",
        "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxx" }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Binary

When using a pre-built or source-built binary to run the MCP server, add the following configuration to your Claude Desktop's claude_desktop_config.json file, which you can access from Claude Desktop's Settings > Developer > Edit Config button on the Local MCP servers page.

{
  "mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx"
      }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Cursor

You can configure Cursor to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, add the relevant configuration to your Cursor's mcp.json file, which is usually located in your home directory's .cursor sub-directory.

To access the mcp.json file through the Cursor app to implement this configuration:

  1. From your Cursor Settings, select MCP & Integrations.
  2. Under MCP Tools, select Add Custom MCP to open the mcp.json file.
  3. Implement one of the following required updates to this file, where if you have other MCP servers configured in Cursor, just add the "buildkite": { ... } object to this JSON file.

Docker

When using Docker to run the MCP server, add the following JSON configuration to your Cursor mcp.json file.

{
  "mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server",
        "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxx" }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Binary

When using a pre-built or source-built binary to run the MCP server, add the following JSON configuration to your Cursor mcp.json file.

{
  "mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx"
      }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Goose

You can configure your Goose AI tool or agent to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, add the relevant configuration the extensions: section of your Goose config.yaml file.

Docker

When using Docker to run the MCP server, add the following YAML configuration the extensions: section of your Goose config.yaml file.

extensions:
  fetch:
    name: Buildkite
    cmd: docker
    args: ["run", "--pull=always", "-q", "-i", "--rm",
           "-e", "BUILDKITE_API_TOKEN",
           "buildkite/mcp-server",
           "stdio"]
    enabled: true
    envs: { "BUILDKITE_API_TOKEN": "bkua_xxxxx" }
    type: stdio
    timeout: 300

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Binary

When using a pre-built or source-built binary to run the MCP server, add the following YAML configuration the extensions: section of your Goose config.yaml file.

extensions:
  fetch:
    name: Buildkite
    cmd: buildkite-mcp-server
    args: [stdio]
    enabled: true
    envs: |
      {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx"
      }
    type: stdio
    timeout: 300

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Visual Studio Code

You can configure Visual Studio Code to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, add the relevant configuration to your Visual Studio Code's mcp.json file.

Docker

When using Docker to run the MCP server, add the following JSON configuration to your Visual Studio Code's mcp.json file.

{
  "inputs": [
    {
      "id": "BUILDKITE_API_TOKEN",
      "type": "promptString",
      "description": "Enter your Buildkite API access token",
      "password": true
    }
  ],
  "servers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server",
        "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "${input:BUILDKITE_API_TOKEN}" }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Alternatively, you can initiate this process through the Visual Studio Code interface. To do this:

  1. In the Command Palette, find and select the MCP: Add Server command.
  2. Select Docker image to start configuring your local MCP server running in Docker.
  3. For Enter Docker Image Name, specify buildkite/mcp-server, and Allow it to be installed.
  4. For Enter your Buildkite API Access Token, enter your configured Buildkite API access token.

  5. For Enter Server ID, specify buildkite.

    Follow the remaining prompts to complete this configuration process.

Binary

When using a pre-built or source-built binary to run the MCP server, add the following JSON configuration to your Visual Studio Code's mcp.json file.

{
  "inputs": [
    {
      "id": "BUILDKITE_API_TOKEN",
      "type": "promptString",
      "description": "Enter your Buildkite API access token",
      "password": true
    }
  ],
  "servers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN": "${input:BUILDKITE_API_TOKEN}"
      }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Windsurf

You can configure Windsurf to work with your local Buildkite MCP server, running in Docker or as a binary. To do this, add the relevant configuration to your Windsurf's mcp_config.json file.

Docker

When using Docker to run the MCP server, add the following JSON configuration to your Windsurf's mcp_config.json file.

{
  "mcpServers": {
    "buildkite": {
      "command": "docker",
      "args": [
        "run", "--pull=always", "-q", "-i", "--rm", "-e", "BUILDKITE_API_TOKEN",
        "buildkite/mcp-server",
        "stdio"
      ],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxx" }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Binary

When using a pre-built or source-built binary to run the MCP server, add the following JSON configuration to your Windsurf's mcp_config.json file.

{
  "mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": {
        "BUILDKITE_API_TOKEN": "bkua_xxxxx"
      }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

Zed

You can configure the Zed code editor with the Buildkite MCP server as a locally running binary using the Zed Buildkite MCP extension.

To add the Buildkite MCP server extension to Zed:

  1. Visit Zed's Buildkite MCP server extension page.
  2. Select the Install MCP Server in Zed button on this web page to open the Extensions window in Zed.
  3. In the Extensions window, ensure the Buildkite MCP extension is shown and select its Install button.
  4. In the Configure mcp-server-buildkite dialog, copy your configured Buildkite API access token and paste this over the BUILDKITE_API_TOKEN value.

  5. Select Configure Server to save the changes.

    Your configuration should be saved to the Zed's main settings.json file, which is usually located within your home directory's .config/zed/ folder.

Alternatively, you can copy and paste the following configuration as a new entry to Zed's main settings.json file, bearing in mind that if you had previously configured an MCP server in Zed, add just the "mcp-server-buildkite" object within the existing "context_servers" object of this file.

{
  "context_servers": {
    "mcp-server-buildkite": {
      "settings": {
        "buildkite_api_token": "bkua_xxxxx"
      }
    }
  }
}

where bkua_xxxxx is the value of your configured Buildkite API access token, set with your required scopes.

ToolHive

ToolHive is a tool that allows you to abstract the API access token handling processes for your local Buildkite MCP server, away from your other AI tool infrastructure and the Buildkite platform.

You can configure ToolHive to run your local Buildkite MCP server from its registry using ToolHive's command line interface (CLI) tool. To do this, ensure you have installed TooHive's CLI tool and do the following:

  1. Use ToolHive's thv secret set command to store your Buildkite API access token as a secret.

    cat ~/path/to/your/buildkite-api-token.txt | thv secret set buildkite-api-key

    where buildkite-api-token.txt contains the value of your Buildkite API access token.

  2. Run the Buildkite MCP server.

    thv run --secret buildkite-api-key,target=BUILDKITE_API_TOKEN buildkite

You can also configure ToolHive to run your local Buildkite MCP server from its registry using the ToolHive interface. To do this, ensure you have installed TooHive's Desktop app and do the following:

  1. Access ToolHive's Secrets page.

  2. Add a new secret with the following values:

  3. Access ToolHive's Registry page.

  4. Search for buildkite and then select the filtered buildkite registry option.

  5. Select Install server and on the Configure buildkite dialog's Configuration tab, specify the following values:

    • Secrets: Select buildkite-api-key.
    • Environment variables (optional): Specify the threshold for logging tokens. Omitting this field sets its value to 0, which means that no tokens are logged.