What is Buildkite Mcp

buildkite-mcp is a Model Context Protocol (MCP) server designed for integration with Buildkite, allowing users to retrieve information about organizations, pipelines, and builds.

Use cases

Use cases for buildkite-mcp include automating the retrieval of build statuses, integrating Buildkite data into other applications, and providing a centralized API for managing CI/CD workflows.

How to use

To use buildkite-mcp, clone the repository, install dependencies with ‘npm install’, set the ‘BUILDKITE_ACCESS_TOKEN’ environment variable, and start the server with ‘node index.js’. For integration with Cursor, configure it in the mcp.json file.

Key features

Key features include the ability to list organizations, pipelines, and builds, as well as retrieve detailed information about specific builds through various MCP endpoints.

Where to use

buildkite-mcp is primarily used in software development environments where Buildkite is employed for continuous integration and deployment, facilitating automation and monitoring of build processes.

Buildkite MCP Server

A microservice for retrieving information from Buildkite via Model Context Protocol (MCP).

Setup

1. Clone this repository
2. Run npm install
3. Set the BUILDKITE_ACCESS_TOKEN environment variable
4. Start the server with node index.js

Using with Cursor (MCP Integration)

To add this server to Cursor, you need to configure it in your ~/.cursor/config/mcp.json file:

{
  "mcpServers": {
    "buildkite": {
      "command": "npx",
      "args": [
        "-y",
        "@drew-goddyn/buildkite-mcp"
      ],
      "env": {
        "BUILDKITE_ACCESS_TOKEN": "your-buildkite-access-token"
      }
    }
  }
}

With this configuration:

• You don’t need to install or run the server manually
• Cursor will automatically start and stop the server as needed
• Replace your-buildkite-access-token with your actual Buildkite API token

After updating the configuration, restart Cursor to apply the changes.

MCP Endpoints

List Organizations

POST /mcp_buildkite_list_organizations

Request Body:

{
  "access_token": "optional-if-set-in-env"
}

Response:

[
  {
    "id": "org-id",
    "name": "Organization Name",
    "slug": "organization-slug"
  }
]

List Pipelines

POST /mcp_buildkite_list_pipelines

Request Body:

{
  "organization": "my-org",
  "access_token": "optional-if-set-in-env"
}

Response:

[
  {
    "id": "pipeline-id",
    "name": "Pipeline Name",
    "slug": "pipeline-slug"
  }
]

List Builds

POST /mcp_buildkite_list_builds

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "access_token": "optional-if-set-in-env",
  "branch": "main",
  "state": "failed",
  "per_page": 10,
  "page": 1
}

Response:

[
  {
    "id": "build-id",
    "number": 123,
    "state": "failed"
  }
]

Get Build Details

POST /mcp_buildkite_get_build

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "build_number": 123,
  "access_token": "optional-if-set-in-env"
}

Response:

{
  "id": "build-id",
  "number": 123,
  "jobs": [
    {
      "id": "job-id",
      "name": "Job Name",
      "state": "failed"
    }
  ]
}

List All Jobs

POST /mcp_buildkite_list_jobs

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "build_number": 123,
  "access_token": "optional-if-set-in-env"
}

Response:

[
  {
    "id": "job-id",
    "name": "Job Name",
    "state": "failed"
  }
]

List Failed Jobs

POST /mcp_buildkite_list_failed_jobs

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "build_number": 123,
  "access_token": "optional-if-set-in-env"
}

Response:

[
  {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Test Job",
    "state": "failed",
    "web_url": "https://buildkite.com/my-org/my-pipeline/builds/123#01234567-89ab-cdef-0123-456789abcdef"
  }
]

List Job Spec Failures

POST /mcp_buildkite_list_job_spec_failures

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "build_number": 123,
  "job_id": "01234567-89ab-cdef-0123-456789abcdef",
  "access_token": "optional-if-set-in-env"
}

Response:

[
  {
    "type": "RSpec",
    "spec": "./spec/path/to/file_spec.rb:123",
    "message": "Expected result to be X but got Y"
  }
]

Get Job Log

POST /mcp_buildkite_get_job_log

Request Body:

Response:

{
  "content": "...log content...",
  "size": 12345,
  "format": "raw"
}

List Failed Specs from Build URL

POST /mcp_buildkite_list_failed_specs

Request Body:

{
  "build_url": "https://buildkite.com/my-org/my-pipeline/builds/123",
  "access_token": "optional-if-set-in-env"
}

Response:

{
  "build_url": "https://buildkite.com/my-org/my-pipeline/builds/123",
  "failed_job_count": 2,
  "jobs": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Test Job 1",
      "web_url": "https://buildkite.com/my-org/my-pipeline/builds/123#01234567-89ab-cdef-0123-456789abcdef",
      "failures": [
        {
          "spec": "./spec/path/to/file_spec.rb:123",
          "message": "Expected result to be X but got Y"
        }
      ]
    },
    {
      "id": "fedcba98-7654-3210-fedc-ba9876543210",
      "name": "Test Job 2",
      "web_url": "https://buildkite.com/my-org/my-pipeline/builds/123#fedcba98-7654-3210-fedc-ba9876543210",
      "failures": []
    }
  ],
  "failures": [
    {
      "job_id": "01234567-89ab-cdef-0123-456789abcdef",
      "job_name": "Test Job 1",
      "job_url": "https://buildkite.com/my-org/my-pipeline/builds/123#01234567-89ab-cdef-0123-456789abcdef",
      "spec": "./spec/path/to/file_spec.rb:123",
      "message": "Expected result to be X but got Y"
    }
  ]
}

Retry Job

POST /mcp_buildkite_retry_job

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "build_number": 123,
  "job_id": "01234567-89ab-cdef-0123-456789abcdef",
  "access_token": "optional-if-set-in-env"
}

Response:

{
  "id": "job-id",
  "state": "scheduled"
}

List Pipeline Build Failures

POST /mcp_buildkite_list_pipeline_build_failures

Request Body:

{
  "organization": "my-org",
  "pipeline": "my-pipeline",
  "state": "finished",
  "per_page": 10,
  "page": 1,
  "access_token": "optional-if-set-in-env"
}

Response:

[
  {
    "build_number": 123,
    "build_url": "https://buildkite.com/my-org/my-pipeline/builds/123",
    "failed_jobs": [
      {
        "name": "Test Job",
        "url": "https://buildkite.com/my-org/my-pipeline/builds/123#01234567-89ab-cdef-0123-456789abcdef"
      }
    ]
  }
]

Environment Variables

• BUILDKITE_ACCESS_TOKEN: Your Buildkite API token with read access
• PORT: (Optional) Port to run the server on (default: 63330)

Error Handling

The server returns appropriate HTTP status codes and error messages when something goes wrong:

• 400: Bad Request - Missing or invalid parameters
• 401: Unauthorized - Invalid or missing access token
• 404: Not Found - Resource not found
• 500: Internal Server Error - Server-side error