Jenkins MCP Server (Go)

Overview

Purpose: Pure Go MCP server exposing Jenkins API functionality as MCP tools.
Transport: stdio (newline-delimited JSON) via mcp-go-sdk.

Features

Tool: jenkins_get_jobs
- Description: Get list of Jenkins jobs with their current status
- Arguments: None
- Returns: JSON array of jobs with basic information: name, url, color, buildable, description, and lastBuild when available
Tool: jenkins_get_job
- Description: Get detailed information about a specific Jenkins job by name, including the last 10 builds and any queued items for this job
- Arguments: name (required) - Name of the Jenkins job
- Returns: JSON object with detailed job information including recent build history and queuedBuilds (if present)
Tool: jenkins_get_running_builds
- Description: Get list of currently running and queued Jenkins builds
- Arguments: None
- Returns: JSON object with:
  - builds: running builds with fields: jobName, buildNumber, url, startTime (RFC3339 string), duration (human-readable), optional progress
  - queuedBuilds: queued items with fields: jobName, url, queueId, why, queuedSince (RFC3339 string), stuck, buildable, optional parameters
Tool: jenkins_get_build_logs
- Description: Get build logs for a specific Jenkins job and build number with pagination support
- Arguments:
  - job_name (required) - Name of the Jenkins job
  - build_number (required) - Build number to get logs for
  - offset (optional, default: 0) - Starting byte offset in the log file
  - length (optional, default: 8192) - Maximum number of bytes to retrieve
- Returns: Plain text log content for the requested slice
Tool: jenkins_get_build_log_tail
- Description: Get the tail of build logs - useful for quick failure analysis
- Arguments:
  - job_name (required) - Name of the Jenkins job
  - build_number (required) - Build number to get logs for
  - max_length (optional, default: 8192) - Maximum number of bytes to retrieve from the end
- Returns: Plain text tail log content
Tool: jenkins_start_job
- Description: Trigger a Jenkins job build with optional parameters
- Arguments:
  - job_name (required) - Name/path of the Jenkins job (supports folders)
  - parameters (optional) - Object map of build parameters
- Returns: JSON with jobName and queueUrl (if available); may also include buildUrl and buildNumber when retrievable from the queue item.
Tool: jenkins_wait_for_running_build
- Description: Wait for a running Jenkins build to complete or timeout
- Arguments:
  - job_name (required) - Name of the Jenkins job
  - build_number (required) - Build number to wait for
  - timeout_seconds (optional, default: 600) - Maximum time to wait in seconds
- Returns: JSON object with build completion status and timing information

Job Format Each job returned by jenkins_get_jobs and jenkins_get_job includes:

{
  "name": "job-name",
  "url": "https://jenkins.example.com/job/job-name/",
  "color": "blue",
  "buildable": true,
  "description": "Job description",
  "recentBuilds": [
    {
      "number": 123,
      "url": "https://jenkins.example.com/job/job-name/123/",
      "building": false,
      "result": "SUCCESS",
      "timestamp": "2023-08-21T12:00:00Z",
      "duration": "2m0s"
    },
    {
      "number": 122,
      "url": "https://jenkins.example.com/job/job-name/122/",
      "building": false,
      "result": "SUCCESS",
      "timestamp": "2023-08-21T11:40:00Z",
      "duration": "1m58s"
    }
  ],
  "parameters": [
    {
      "name": "MERGE_FEATURE",
      "type": "StringParameterDefinition",
      "description": "Feature branch to merge",
      "defaultValue": "",
      "choices": []
    },
    {
      "name": "BUILD_TYPE",
      "type": "ChoiceParameterDefinition",
      "description": "Type of build to perform",
      "defaultValue": "release",
      "choices": ["debug", "release", "test"]
    }
  ]
}

Note: recentBuilds are sorted by build number (descending - most recent first) and both lastBuild and recentBuilds fields are omitted when empty.

Note: The jenkins_get_job tool returns individual jobs with full parameter information and recent build history (last 10 builds, sorted by number descending), while jenkins_get_jobs returns only basic job fields (no parameters or recentBuilds) for performance; it may include lastBuild when available.

Running Build Format Each running build returned by jenkins_get_running_builds includes:

{
  "jobName": "job-name",
  "buildNumber": 124,
  "url": "https://jenkins.example.com/job/job-name/124/",
  "startTime": "2023-08-21T12:01:40Z",
  "duration": "45s",
  "progress": 75
}

Queued Build Format Each queued build item includes:

{
  "jobName": "job-name",
  "url": "https://jenkins.example.com/job/job-name/",
  "queueId": 19069,
  "why": "Build is waiting for an available executor",
  "queuedSince": "2023-08-21T12:01:00Z",
  "stuck": false,
  "buildable": true,
  "parameters": "PARAM1=foo\nPARAM2=bar"
}

Build Logs Result jenkins_get_build_logs returns plain text containing the requested portion of the log. Control pagination via the offset and length arguments. Example output:

Started by user admin
Building in workspace /var/lib/jenkins/workspace/job-name
...

Wait for Build Format Build wait results returned by jenkins_wait_for_running_build include:

{
  "jobName": "job-name",
  "buildNumber": 124,
  "status": "success",
  "result": "SUCCESS",
  "duration": "2m0s",
  "waitTime": "45s",
  "timedOut": false
}

Status values:

success: Build completed successfully
failure: Build failed
unstable: Build completed but with test failures or warnings
aborted: Build was manually aborted
timeout: Wait operation timed out before build completed
unknown: Build completed with an unrecognized result

Jenkins Color Codes

blue: Last build was successful
red: Last build failed
yellow: Last build was unstable
grey: Job has never been built
disabled: Job is disabled
aborted: Last build was aborted
*_anime: Job is currently building (e.g., blue_anime)

Requirements

CLI: -url <jenkins_url> (required) - Jenkins server URL
CLI: -auth "<user>:<api_token>" (optional) - Jenkins authentication credentials
ENV: JENKINS_MCP_AUTH="<user>:<api_token>" (optional) - Alternative to -auth flag
CLI: -stdio (default true) for stdio, or -http <addr> for Streamable HTTP.

Authentication Authentication can be provided in two ways:

Command line flag: -auth "user:token"
Environment variable: JENKINS_MCP_AUTH="user:token"

If both are provided, the -auth flag takes precedence.

Run (stdio)

Build: go build -o jenkins-mcp-go .
Run (stdio): execute with required parameters; an MCP host (e.g., Claude Desktop) should launch this binary with stdio wiring.

Examples:

JENKINS_MCP_AUTH="myuser:myapitoken" ./jenkins-mcp-go -url "https://jenkins.example.com"
HTTP mode: JENKINS_MCP_AUTH="myuser:myapitoken" ./jenkins-mcp-go -url "https://jenkins.example.com" -http :8080

Smithery / Hosts

Configure your MCP host to run this server over stdio with the required parameters.

API Details

Uses Jenkins REST API /api/json endpoint to fetch job list
Uses Jenkins REST API /job/{jobName}/api/json endpoint to fetch specific job details
Uses Jenkins REST API /computer/api/json endpoint to fetch running builds from executors
Uses Jenkins REST API /job/{jobName}/{buildNumber}/logText/progressiveText endpoint for build logs
Implements smart tail log retrieval by calculating offset from total log size
Implements proper basic authentication and includes Jenkins CSRF crumb for build triggers when available
30-second timeout for API calls, 60-second timeout for log retrieval
Graceful error handling for missing jobs/builds
Parses job names and build numbers from executor information
Supports nested jobs/folders via Jenkins path convention /job/<seg>/job/<seg>/... and proper URL escaping
Supports log pagination with offset and length parameters
Optimized tail log retrieval for quick failure analysis

Notes

Input validation: enforces required URL and auth parameters
Auth format: must be "user:api_token" format
Errors: returned as tool results with isError=true for LLM visibility
Timestamps are RFC3339 strings; durations are human-readable (e.g., "45s", "2m5s")

Transport

-http <addr> starts Streamable HTTP; otherwise -stdio runs by default.
If -stdio=false and no -http is provided, the server exits with an error.

TODO

Add more Jenkins tools (get build status, etc.)
Add filtering options (by job name pattern, status, etc.)
Add SSL certificate validation options
Optionally return structured metadata for log tools
Optional wait behavior modes for jenkins_start_job

simonfxr/go-jenkins-mcp

Jenkins MCP Server (Go)