Skip to main content
Glama
Drone CI MCP Server

Drone CI MCP Server

by leuzeus

mcp-drone-ci

MCP server scaffold for Drone CI.

Status

This repository currently provides:

  • a TypeScript project scaffold,

  • a working Drone HTTP client (read + action endpoints),

  • a real MCP server entrypoint on stdio (SDK-based),

  • MCP tool/resource definitions for Drone CI monitoring,

  • webhook parsing and HMAC signature verification,

  • optional Drone webhook HTTP receiver with in-memory build-state cache,

  • basic policy/state modules,

  • initial unit tests.

Still pending before production use:

  • webhook event processing to store richer build metadata from payloads,

  • persistence backend (DB/Redis) for state beyond process memory,

  • broader integration tests against mock Drone API/webhook payloads.

Related MCP server: AWS AppRunner MCP Server

Implementation Plan

See docs/implementation-plan.md.

Requirements

  • Node.js 20+

  • npm 10+

Quick Start

  1. Install dependencies:

npm install
  1. Review the required environment variables:

cp .env.example .env

Then export the values in your shell or pass them explicitly in your MCP client configuration. This project does not load .env automatically. 3. Build:

npm run build
  1. Run tests:

npm test
  1. Start:

npm start

Run As MCP (stdio)

npm start launches the MCP server on stdio. Configure your MCP client to spawn:

  • command: node

  • args: dist/index.js

  • env: DRONE_BASE_URL, optional tuning vars (and DRONE_WEBHOOK_SECRET only if webhook is enabled)

Example MCP config:

{
  "mcpServers": {
    "drone-ci": {
      "command": "node",
      "args": ["G:\\projets\\mcp-drone-ci\\dist\\index.js"],
      "env": {
        "DRONE_BASE_URL": "https://drone.example.com",
        "DRONE_TOKEN": "replace-with-drone-token",
        "MCP_ENABLE_WRITE_ACTIONS": "false",
        "MCP_WEBHOOK_PORT": "0",
        "MCP_RECONCILE_INTERVAL_MS": "5000"
      }
    }
  }
}

Windows/JetBrains/Codex note:

  • do not rely on custom parent environment variables such as DRONE_BASE_URL or DRONE_TOKEN being inherited automatically by a local stdio MCP process,

  • many MCP stdio launchers only forward a safe subset of environment variables, so DRONE_* values must usually be set explicitly in the server env block,

  • do not set DRONE_TOKEN to a placeholder like "${DRONE_TOKEN}" in MCP env if your client does not expand placeholders; otherwise the literal string is sent and Drone authentication fails (401).

Client compatibility note:

  • MCP tool inputSchema values are intentionally kept permissive to improve compatibility with clients such as JetBrains and Codex.

  • Strict business validation still happens in the tool handlers, so invalid empty strings or non-positive integers are rejected at execution time rather than at MCP discovery/schema time.

  • drone_ping is available as a minimal no-input diagnostic tool to verify that a client can discover and invoke tools correctly.

Real-time CI Tracking

To enable webhook-driven state cache:

  1. Set MCP_WEBHOOK_PORT to a non-zero port (for example 8080).

  2. Set DRONE_WEBHOOK_SECRET to the shared secret configured in Drone.

  3. Configure Drone webhook target to:

    • http://<host>:<MCP_WEBHOOK_PORT><MCP_WEBHOOK_PATH>

    • default path is /webhook/drone

Optional fallback polling:

  • set MCP_RECONCILE_INTERVAL_MS (for example 5000) to periodically refresh active builds from Drone API.

MCP Tools

Read tools:

  • drone_ping: minimal diagnostic tool returning { ok: true, server: "mcp-drone-ci" }

  • drone_list_repos: list repositories visible to the Drone token

  • drone_list_builds: list build summaries for a repository

  • drone_get_build: fetch full details for one build

  • drone_get_build_logs: fetch one stage/step log stream, with optional truncation

  • drone_get_cached_build_state: inspect webhook-cached build state

Action tools (only when MCP_ENABLE_WRITE_ACTIONS=true):

  • drone_restart_build

  • drone_stop_build

  • drone_approve_build

  • drone_decline_build

Build filters supported by drone_list_builds:

  • owner and repo are always required

  • optional prNumber

  • optional sourceBranch

  • optional targetBranch

  • optional page and limit

Numeric inputs:

  • build identifiers and pagination values are exposed as generic MCP numbers for broad client compatibility

  • integer, positivity, and max-value checks are enforced by the server when the tool is executed

  • filtered drone_list_builds searches report when the repository scan limit is hit, instead of silently returning a false negative

Example:

{
  "name": "drone_list_builds",
  "arguments": {
    "owner": "leuzeus",
    "repo": "gowire",
    "prNumber": 510,
    "sourceBranch": "S076-gcmp-v2-planning",
    "targetBranch": "dev",
    "limit": 5
  }
}

Token Efficiency

This MCP is designed so agents can stay efficient if they use the tools in the intended order:

  1. Use drone_list_builds to search.

  2. Use drone_get_build only for the specific build you want to inspect in detail.

  3. Use drone_get_build_logs with limitChars when you need failure evidence.

Important behavior:

  • drone_list_builds returns compact build summaries, not full build payloads

  • the full build message and other verbose fields are reserved for drone_get_build

  • MCP JSON responses are serialized compactly to reduce token overhead

Recommended agent patterns:

  • prefer owner/repo + prNumber for PR-centric queries

  • otherwise use owner/repo + sourceBranch + targetBranch

  • keep limit small whenever possible

  • avoid drone_list_repos unless cross-repository discovery is explicitly needed

  • avoid broad drone_list_builds calls without filters on large repositories

Recommended order of precision:

  1. owner/repo + buildNumber

  2. owner/repo + prNumber

  3. owner/repo + sourceBranch + targetBranch

  4. owner/repo + targetBranch

Environment Variables

Required:

  • DRONE_BASE_URL: Drone base URL (for example https://drone.example.com)

  • DRONE_TOKEN: Drone API token

Optional:

  • DRONE_ALLOW_INSECURE_HTTP (default false, only set true for trusted internal Drone deployments without TLS)

  • DRONE_TIMEOUT_MS (default 10000)

  • DRONE_MAX_RETRIES (default 2)

  • MCP_ENABLE_WRITE_ACTIONS (default false)

  • MCP_RECONCILE_INTERVAL_MS (default 0, disabled)

  • MCP_WEBHOOK_PORT (default 0, disabled)

  • MCP_WEBHOOK_PATH (default /webhook/drone)

  • DRONE_WEBHOOK_SECRET (required when MCP_WEBHOOK_PORT > 0)

Security Notes

  • Do not commit real tokens or webhook secrets.

  • Keep .env local and use .env.example as template only.

  • Use a read-only Drone token by default.

  • Keep write actions disabled (MCP_ENABLE_WRITE_ACTIONS=false) until authorization guardrails are in place.

Repository Protection

This repository is configured to enforce:

  • branch protection on main (PR required, stale review dismissal),

  • required status check (test),

  • linear history and no force-push,

  • signed commits on protected branch,

  • secret scanning and push protection,

  • Dependabot security updates.

Available Tools

6 tools
drone_get_buildC

Get one build details by build number.

Inputs: owner (required), repo (required), buildNumber (required).

drone_get_build_logsC

Get logs for one build stage/step.

Inputs: owner (required), repo (required), buildNumber (required), stageNumber (required), +2 more.

drone_get_cached_build_stateB

Read webhook-cached build state. If buildNumber is omitted, returns recent snapshots for the repository.

Inputs: owner (required), repo (required), buildNumber, limit.

drone_list_buildsC

List builds for a repository.

Inputs: owner (required), repo (required), page, limit, +3 more.

drone_list_reposC

List repositories visible to the Drone token.

Inputs: page, limit.

drone_pingA

Minimal diagnostic tool for MCP client compatibility checks.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct purpose: build details, logs, cached state, listing builds, listing repos, and a ping diagnostic. No overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent drone_<verb>_<noun> pattern, making them predictable and easy to navigate.

    Tool Count5/5

    Six tools is well-scoped for a CI integration, covering core retrieval operations without unnecessary bloat.

    Completeness3/5

    The set focuses on read-only operations (get, list, ping) but lacks build creation, cancellation, or update actions, which are common for CI workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A TypeScript-based MCP server that provides backend API handling and facilitates communication between microservices. Features an organized structure with controllers, routes, and models for easy extensibility and maintenance.
      1
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      A TypeScript-based template for rapidly developing MCP servers with modular tool architecture, built-in validation using Zod schemas, and comprehensive error handling.
      5 npm
      MIT