buildkite-mcp-server 🚀

Model Context Protocol (MCP) server exposing Buildkite data (pipelines, builds, jobs, tests) to AI tooling and editors.

⚡ TL;DR Quick-start

Create a Buildkite API Token

# Run via Docker with the token from above
docker run --pull=always -q -it --rm -e BUILDKITE_API_TOKEN=bkua_xxxxx buildkite/mcp-server stdio

🗂️ Table of Contents

• Prerequisites
• API Token Scopes
• Installation
• Configuration & Usage
• Features
• Screenshots
• Security
• Contributing
• License

🛠️ Prerequisites

🔑 API Token Scopes

All READ and WRITE functionality

👉 Quick add: Create token with READ and WRITE functionality

Includes all READONLY and Minimum scopes listed below.

All READONLY functionality

👉 Quick add: Create token with READONLY functionality

Includes Minimum scopes listed below.

Minimum recommended

👉 Quick add: Create token with Basic functionality

Note: Tools requiring write access, like unblock_job, create_build and create_pipeline require the "All READ and WRITE functionality" token.

📦 Installation

1. Docker (recommended)

docker pull buildkite/mcp-server

Run:

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

2. Pre-built binary

Download the latest release from GitHub Releases. Binaries are fully-static and require no libc.

If you're on macOS, you can use Homebrew:

brew install buildkite/buildkite/buildkite-mcp-server

3. Build from source

go install github.com/buildkite/buildkite-mcp-server@latest
# or
goreleaser build --snapshot --clean
# or
make build    # uses goreleaser (snapshot)

4. Docker Desktop

docker mcp server enable buildkite

View on Docker MCP Hub

⚙️ Configuration & Usage

# ~/.config/amp/settings.json
{
  "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_xxxxxxxx" }
    }
  }
}

# ~/.config/amp/settings.json
{
  "amp.mcpServers": {
    "buildkite": {
      "command": "buildkite-mcp-server",
      "args": ["stdio"],
      "env": { "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx", "JOB_LOG_TOKEN_THRESHOLD": "2000" }
    }
  }
}

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

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

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

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

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

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

{
  "buildkite": {
    "command": "buildkite-mcp-server",
    "args": ["stdio"],
    "env": {
      "BUILDKITE_API_TOKEN": "bkua_xxxxxxxx",
      "JOB_LOG_TOKEN_THRESHOLD": "2000"
    }
  }
}

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_xxxxxxxx" }
    type: stdio
    timeout: 300

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

{
  "inputs": [
    {
      "id": "BUILDKITE_API_TOKEN",
      "type": "promptString",
      "description": "Enter your Buildkite 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}" }
    }
  }
}

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

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

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

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

// ~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-server-buildkite": {
      "settings": {
        "buildkite_api_token": "your-buildkite-token-here"
      }
    }
  }
}

🔧 Environment Variables

🛠️ Tools & Features

🔍 Job Log Analysis Tools

Inspect Buildkite job logs in milliseconds, with full-text search, tail, and structured reads – all from one endpoint.

The server ships with four log analysis tools that convert Buildkite job output to structured Parquet data for efficient querying:

• search_logs – Regex search with context lines for debugging failures
• tail_logs – Show last N lines for recent errors and status checks
• read_logs – Stream log entries from specific positions
• get_logs_info – File metadata and statistics before reading content

Smart Caching & Storage

The first request downloads and converts logs to Parquet format; subsequent requests are zero-API calls with near-instant response times. All tools return token-efficient JSON by default for optimal AI/LLM performance.

💡 Zero-config setup: Don't set anything for local testing—the server auto-picks the right directory. Set BKLOG_CACHE_URL to override with S3 (s3://bucket/path), GCS, Azure, or custom storage backends.

Examples:

# Local development with persistent cache
export BKLOG_CACHE_URL="file:///Users/me/bklog-cache"

# Shared cache across build agents
export BKLOG_CACHE_URL="s3://ci-logs-cache/buildkite/"

🌐 Streamable HTTP / SSE transport

You can also run the MCP server using the Streamable HTTP Transport, and connect to the MCP server at http://localhost:3000/mcp.

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

Or with the legacy HTTP/SSE transport, and connect to the MCP server at http://localhost:3000/sse.

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

You can also set the listen address via environment variable:

HTTP_LISTEN_ADDR="localhost:4321" buildkite-mcp-server http

To run the server with Streamable HTTP transport in a docker and expose on 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

[!CAUTION] By default, Docker will bind published ports on all interfaces, making your MCP server accessible from any devices on your local network. We recommend using the default stdio transport when used locally, but if you must use HTTP/SSE, binding the forwarded port to 127.0.0.1, as in the example above will prevent other devices on your local network from accessing the server.

📸 Screenshots

🤖 AGENTS.md

We recommend adding a hint to your AGENTS.md, or equivalent agent configuration file, for example CLAUDE.md ect. This will typically be under an architecture section.

This hint will orientate the agent towards using the buildkite MCP to quickly diagnose build issues, or return project level CI/CD insights quickly. You should replace the organization, pipeline slug(s) and pipeline files based on your project.

- **CI/CD**: `buildkite` organization, `buildkite-mcp-server` pipeline slug for build and test (`.buildkite/pipeline.yml`), `buildkite-mcp-server-release` pipeline slug for releases (`.buildkite/pipeline.release.yml`)

📚 Library Usage

The exported Go API of this module should be considered unstable, and subject to breaking changes as we evolve this project.

🔒 Security

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

This image is built from cgr.dev/chainguard/static and runs as an unprivileged user.

🤝 Contributing

Development guidelines are in DEVELOPMENT.md.

Run the test suite:

go test ./...

📝 License

MIT © Buildkite

SPDX-License-Identifier: MIT