GoCD MCP Server

GoCD MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with GoCD, a continuous delivery platform, through AI assistants.

This server enables AI assistants to query and manage GoCD pipelines, stages, and jobs via the MCP protocol. It acts as a bridge between AI tools and the GoCD REST API.

Available Tools

Pipeline Management

• list_pipelines - Browse all pipelines with their groups and pause status
• get_pipeline_status - Check if a pipeline is running, paused, or locked
• get_pipeline_history - View recent pipeline runs and their results
• get_pipeline_instance - Get detailed information about a specific pipeline run
• trigger_pipeline - Manually start a pipeline run
• pause_pipeline / unpause_pipeline - Control pipeline scheduling

Stage Operations

• get_stage_instance - View stage details including all jobs and their status
• trigger_stage - Manually trigger or retry a stage
• cancel_stage - Stop a running stage

Job Analysis

• parse_gocd_url - Extract pipeline/stage/job info from GoCD URLs
• analyze_job_failures - Get comprehensive failure analysis including test results and console logs
• get_job_history - View job execution history
• get_job_instance - Check job status and details
• get_job_console - Read build logs and error output
• list_job_artifacts - Browse artifacts produced by a job
• get_job_artifact - Download specific artifact files
• parse_junit_xml - Extract structured test results from JUnit XML reports

Example Queries

• "Get all errors for this job " - Automatically parses URL and analyzes failures
• "Show me why the build failed" - Finds test failures and build errors
• "List all pipelines" - Browse available pipelines
• "Trigger the deployment stage" - Manually run a stage

GoCD API Compatibility

This MCP server integrates with the GoCD REST API and is compatible with GoCD 19.8.0 and later.

The server uses the following GoCD API versions:

• v1 - Pipeline status, history, instances, jobs
• v2 - Stage triggering
• v3 - Stage instances and cancellation
• v4 - Dashboard and pipeline groups

For detailed API documentation, refer to the GoCD API Reference.

Development

• npm run dev: Run in development mode with tsx
• npm run build: Compile TypeScript to JavaScript
• npm run format: Format code with Prettier
• npm run inspect: Open the MCP inspector for testing (server must be running separately)

The server will listen on the configured host and port (default: http://0.0.0.0:3000).

Configuration

Set the following environment variables on the server:

• GOCD_SERVER_URL: The URL of your GoCD server (e.g., https://gocd.example.com)
• MCP_HOST: Host to bind the MCP server to (default: 0.0.0.0)
• MCP_PORT: Port for the MCP server to listen on (default: 3000)

You can create a .env file in the project root:

GOCD_SERVER_URL=https://your-gocd-server.com
MCP_HOST=0.0.0.0
MCP_PORT=3000

Note: Users connecting to the MCP server will provide their own GoCD API token when authenticating. The server does not require a shared token.

Debug Logging

Enable debug output using the DEBUG environment variable:

# Enable all debug logs
DEBUG=gocd-mcp:* npm run dev

# Enable specific namespaces
DEBUG=gocd-mcp:tools,gocd-mcp:client npm run dev

# With Docker
docker run -d -e DEBUG=gocd-mcp:* --env-file=.env -p 3000:3000 gocd-mcp

Available namespaces:

• gocd-mcp:server - Server startup and shutdown
• gocd-mcp:http - HTTP requests to the MCP endpoint
• gocd-mcp:session - MCP session lifecycle
• gocd-mcp:tools - Tool calls and dispatch
• gocd-mcp:client - GoCD API requests

Deployment

A Dockerfile has been added to this repository you can use it to run the server. Create your .env with the configuration and

docker build -t gocd-mcp .
docker run -d --env-file=.env -p <YOUR_LOCAL_PORT>:<MCP_PORT> gocd-mcp

# With debug logging enabled
docker run -d -e DEBUG=gocd-mcp:* --env-file=.env -p <YOUR_LOCAL_PORT>:<MCP_PORT> gocd-mcp

Testing

npm test

Testing with MCP Inspector

1. Start the server: npm run dev
2. Open the inspector: npm run inspect
3. In the inspector UI, connect to: http://localhost:3000/mcp
4. Add header: Authorization: Bearer YOUR_GOCD_API_TOKEN

Connecting GoCD MCP to your AI

The server communicates via HTTP and exposes the MCP protocol at the /mcp endpoint. Users authenticate by providing their GoCD API token as a Bearer token.

Claude Code

claude mcp add --transport http gocd-mcp https://api.example.com/mcp  --header "Authorization: Bearer your-gocd-token"

GitHub Copilot (VS Code)

Add this server to your Copilot settings:

1. Open VS Code Settings (JSON)
2. Add the MCP server configuration:

{
  "github.copilot.chat.