Buildkite MCP Server Cursor IDE Setup 2026 (Pipelines, Builds, Test Insights)

How do you connect Buildkite to Cursor? Add a buildkite entry to mcp.json that runs the official buildkite/buildkite-mcp-server, installed via Docker (ghcr.io/buildkite/buildkite-mcp-server) or Homebrew (brew install buildkite/buildkite/buildkite-mcp-server), with a BUILDKITE_API_TOKEN environment variable and the stdio argument. Restart Cursor, check for the green dot next to buildkite in Settings → Tools & Integrations → MCP Tools, then ask it to list your pipelines as a first test. If you'd rather skip local install entirely, Buildkite also runs a hosted OAuth server at mcp.buildkite.com/mcp that Cursor can point at directly over HTTP.

This is Buildkite's own server, not a community reimplementation — it's built from cgr.dev/chainguard/static and runs as an unprivileged user in the container, and as of the 2026-07-28 MCP spec update it's a stateless request-response server rather than a long-lived stateful connection, which mostly matters if you're running it behind a load balancer rather than as a single local process. For anyone already on CircleCI or Jenkins for other repos, the shape of what it exposes will feel familiar: pipelines, builds, jobs, logs, and test data, gated behind API token scopes rather than tool-level permission flags.

Quick reference

Prerequisites

Step 1: Decide local vs. remote

Buildkite ships both a local server you run yourself and a hosted remote server, and the choice mostly comes down to whether version pinning matters to you.

Local (Docker or Homebrew) is the right call for automated or scripted workflows where you want a specific, pinned server version rather than whatever Buildkite is currently running upstream.

Remote (mcp.buildkite.com) skips install and updates entirely — Buildkite hosts it, and it's the simpler default for interactive use in an editor. There are three remote paths: a full OAuth-authenticated endpoint, a read-only variant for anyone who wants the tools without write access, and a token pass-through endpoint for setups that already manage Buildkite tokens outside the OAuth flow.

Step 2: Local install — Docker

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

Add it to .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global), with the token supplied as a Cursor input prompt so it isn't hardcoded into the config file:

{
  "inputs": [
    {
      "id": "BUILDKITE_API_TOKEN",
      "type": "promptString",
      "description": "Buildkite API access token (buildkite.com/user/api-access-tokens)",
      "password": true
    }
  ],
  "mcpServers": {
    "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}"
      }
    }
  }
}

Cursor will prompt for the token the first time it starts the server, then reuse it for the session. The trailing stdio argument matters — it's what tells the binary to speak MCP over stdio instead of starting the HTTP server mode.

Step 3: Local install — Homebrew

If you'd rather not manage a Docker image:

brew install buildkite/buildkite/buildkite-mcp-server

Then point mcp.json at the installed binary directly:

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

This form hardcodes the token in the config file, so if the repo (or dotfiles) containing mcp.json is shared or version-controlled, use the Docker + promptString input pattern from Step 2 instead, or keep this file out of source control.

Step 4: Remote server (no local install)

For the OAuth-authenticated hosted server:

{
  "mcpServers": {
    "buildkite": {
      "url": "https://mcp.buildkite.com/mcp"
    }
  }
}

Cursor will walk you through the OAuth flow on first connect — no token to copy-paste. If you only want read access exposed to the agent (no risk of it triggering a build or editing a pipeline), point at the read-only variant instead:

{
  "mcpServers": {
    "buildkite": {
      "url": "https://mcp.buildkite.com/mcp/readonly"
    }
  }
}

Step 5: Scope the token correctly

Buildkite gates every tool call by the scopes attached to your API token — there's no separate per-tool permission system layered on top, so what your token can do is exactly what the agent can do. Three tiers:

Minimum, read-only basics:

Full read-only adds: read_clusters, read_secrets_details, read_artifacts, read_build_logs, read_organizations, read_suites.

Read-write adds on top of all read scopes: write_builds (create builds, unblock jobs, trigger builds), write_pipelines (create, update, delete pipelines), write_secrets (create cluster secrets).

One scope interaction worth knowing before you hit it as a bug: the compare_builds tool specifically needs both read_builds and read_build_logs together — a token with read_builds alone will make most tools work but leave build comparison failing with what looks like a permissions error even though "read builds" sounds sufficient on its own.

If you only want the agent answering questions about pipeline health rather than triggering anything, stop at the read-only tier. Don't add write_builds just to be safe — an agent with the ability to trigger production builds from your editor is a real footgun if it misreads an ambiguous prompt.

Step 6: Verify the connection

List my Buildkite pipelines and tell me which ones have a failing build right now.

or, if you want to test compare_builds specifically:

Compare the last two builds on the [pipeline-name] pipeline and tell me what changed in the failing jobs.

A real answer with actual pipeline and build data confirms the token and scopes are correct. A permissions-style error on compare_builds specifically, while other tools work, means you're missing read_build_logs.

What it exposes

The tool surface is organized around the same scope categories as the token: build management, pipeline operations, cluster administration, secrets metadata, artifact retrieval, build log access, and test suite data. Two tools worth calling out by name because their behavior recently changed: list_jobs now returns compact, summarized job data by default rather than the full payload, specifically to cut down on token usage when an agent is scanning a long build history — and compare_builds, covered above, is the one with the two-scope requirement.

Everything gated behind write_* scopes can mutate state — trigger a build, unblock a blocked step, create or delete a pipeline, write a cluster secret. Everything else is read-only. There's no tool-level toggle independent of the token scopes; if you want an agent that can only look and never touch, the token is where you enforce that, not a config flag on the MCP server itself.

Common mistakes

Forgetting the stdio argument in local mode. Without it, the binary starts in a different run mode and Cursor's stdio-based connection won't get a valid MCP handshake — the server process looks "up" but Cursor reports it as disconnected.

Hardcoding the token in a shared mcp.json. The Homebrew example above works fine for a personal machine, but if that config file is shared across a team or committed to a repo, use the Docker promptString input pattern so the token never lands in a file that gets checked in.

Expecting read_builds alone to cover compare_builds. It doesn't — pair it with read_build_logs, per Step 5.

Granting write scopes by default "to be safe." It's the opposite of safe for an agent that can trigger real CI runs. Start read-only and add write scopes only when you have a specific reason.

Troubleshooting

Server connects but every tool call errors. Confirm the token is valid and hasn't expired at buildkite.com/user/api-access-tokens, and that it's actually attached to the organization whose pipelines you're querying.

compare_builds fails while list_jobs and list_pipelines-style calls succeed. Missing read_build_logs scope — see Step 5.

Docker version works but Homebrew version doesn't (or vice versa). These can drift to different server versions depending on when each was last updated. If one path is broken, docker pull ghcr.io/buildkite/buildkite-mcp-server or brew upgrade buildkite-mcp-server to get both current before debugging further.

Remote OAuth flow doesn't complete. Confirm your browser allows the OAuth redirect back to Cursor, and that you're logging in with the Buildkite account that's actually a member of the organization you want to query.

Related guides

Frequently Asked Questions

Is there an official Buildkite MCP server? Yes — buildkite/buildkite-mcp-server is maintained by Buildkite itself, distributed via Docker (ghcr.io/buildkite/buildkite-mcp-server) and Homebrew (buildkite/buildkite/buildkite-mcp-server), with a hosted remote alternative at mcp.buildkite.com.

Do I need to self-host it, or can I use a remote server? Either works. Local (Docker/Homebrew) is better for pinned versions in automated workflows; the remote OAuth server at mcp.buildkite.com/mcp skips install entirely and is simpler for interactive editor use.

What scopes does my Buildkite API token need? read_builds, read_pipelines, and read_user cover the basics. Add read_build_logs, read_artifacts, read_clusters, read_organizations, read_suites, and read_secrets_details for full read access. Write scopes (write_builds, write_pipelines, write_secrets) are separate and should only be added if you actually want the agent triggering builds or editing pipelines.

Why does compare_builds fail even though other tools work? It requires both read_builds and read_build_logs scopes together — a token with only read_builds will pass for most tools but fail specifically on build comparison.

Can the agent trigger a build or edit a pipeline through this server? Only if the token has write_builds or write_pipelines scopes. Without them, every tool call is read-only regardless of what the agent is asked to do.

Official docs cited