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 <url>" - 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.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:

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

Authentication Failed

If you receive an "UNAUTHORIZED" error:

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

Connection Refused

If you cannot connect to the server:

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

GoCD API Errors

If you receive errors from the GoCD API:

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

Requirements

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

Author

Rushi Vishavadia