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

Start the server: npm run dev
Open the inspector: npm run inspect
In the inspector UI, connect to: http://localhost:3000/mcp
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:

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

{
  "github.copilot.chat.mcp.servers": {
    "gocd": {
      "url": "https://your-mcp-server-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_GOCD_API_TOKEN"
      }
    }
  }
}

Important:

Replace https://your-mcp-server-domain.com with the actual URL where your GoCD MCP server is hosted (e.g., http://localhost:3000 for local development)
Replace YOUR_GOCD_API_TOKEN with your personal GoCD API token (generate from GoCD: User Menu > Personal Access Tokens)
Each user provides their own GoCD API token for authentication

Troubleshooting

"Server not initialized" Error

This error typically occurs when the MCP session is not properly established. To fix:

Ensure the server is running (npm run dev)
Disconnect and reconnect in your MCP client
Verify you're connecting to the correct endpoint: http://localhost:3000/mcp
Make sure you've included the Authorization header with your Bearer token

Authentication Failed

If you receive an "UNAUTHORIZED" error:

Verify your GoCD API token is valid
Check the token has the necessary permissions in GoCD
Ensure the Authorization header is properly formatted: Bearer YOUR_TOKEN
Generate a new token from GoCD (User Menu > Personal Access Tokens)

Connection Refused

If you cannot connect to the server:

Check the server is running: curl http://localhost:3000/health
Verify MCP_HOST and MCP_PORT in your .env file
Check for port conflicts - ensure port 3000 is available
If hosting remotely, ensure firewall rules allow the connection

GoCD API Errors

If you receive errors from the GoCD API:

Verify GOCD_SERVER_URL is correct in your .env file
Ensure the GoCD server is accessible from the MCP server
Check your GoCD server version is 19.8.0 or later
Verify the pipeline/stage/job names are correct

Requirements

Node.js >= 18.0.0 (v22+ recommended for security)

Author

Rushi Vishavadia