jenkins-mcp

A Model Context Protocol (MCP) server for Jenkins, written in Go. Inspect builds, control jobs, and manage pipeline configuration — designed to pair with atlassian-mcp so you can ask "did the build pass?" alongside Jira and Bitbucket questions.

Every install option runs the same single static Go binary: npm (npx @stubbedev/jenkins-mcp), Composer (composer global require stubbedev/jenkins-mcp), a prebuilt binary (go install or a release download), or a Nix flake (nix run github:stubbedev/jenkins-mcp). See Install.

Tools

Inspection

Build control

Job configuration

Natural-language examples

• "did CI pass for this commit?" → jenkins_get_build with sha=<HEAD>

• "why did build #42 fail?" → jenkins_get_tests (failing tests + stack traces) or jenkins_get_log with stageId=<id> for the failing Pipeline stage

• "show me the last 10 builds of master" → jenkins_list_builds

• "what jobs exist under platform/api?" → jenkins_list_jobs with folder=platform/api

• "what's waiting in the queue?" → jenkins_get_queue

• "trigger a build with ENV=production" → jenkins_trigger_build with parameters

• "stop the current build" → jenkins_stop_build with buildNumber

• "add a nightly cron trigger to this job" → jenkins_get_job_config then jenkins_update_job_config with updated triggers

Related MCP server: Jenkins MCP Server

Setup

1. Generate a Jenkins API token

1. In Jenkins, click your username (top-right) → Configure.

2. In the API Token section, click Add new token, give it a name, and click Generate.

3. Copy the token value — it is only shown once.

2. Create a config file

Create ~/.jenkins-mcp.json:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/jenkins-mcp/master/jenkins-mcp.schema.json",
  "url": "https://jenkins.example.com",
  "username": "your-jenkins-login",
  "token": "your-api-token",
  "repoJobMap": {
    "stubbedev/atlassian-mcp": "atlassian-mcp/master",
    "kontainer/api": ["kontainer-api/master", "kontainer-api/PR-builds"]
  }
}

The $schema field is optional but enables editor autocomplete and validation.

repoJobMap keys are matched as case-insensitive substrings against the git remote URL of the current repo, so the server can resolve jobPath automatically when you call jenkins_get_build from inside a repo. Values can be a single job path or an array. Job paths use slashes for nested folders (e.g. folder/sub-folder/job-name).

Alternatively, use environment variables (or a .env file in this directory):

JENKINS_URL=https://jenkins.example.com
JENKINS_USERNAME=your-jenkins-login
JENKINS_TOKEN=your-api-token

Config is resolved in this order: --config <path> CLI arg → JENKINS_MCP_CONFIG env var → ~/.jenkins-mcp.json → $XDG_CONFIG_HOME/jenkins-mcp/config.json (default ~/.config/jenkins-mcp/config.json) → .jenkins-mcp.json in cwd → environment variables.

3. Install

Pick whichever package manager you already have. All of them install the same binary:

MCP clients often start servers without your shell's PATH, so an absolute path is the safest command for any installed option (which jenkins-mcp).

npm / npx

npx downloads the package and the prebuilt binary for your platform on first run, so there is nothing to install up front. npm install -g does the same once and puts jenkins-mcp on your PATH.

npx -y @stubbedev/jenkins-mcp@latest --config ~/.jenkins-mcp.json   # run without installing
npm install -g @stubbedev/jenkins-mcp                               # or install globally → jenkins-mcp

Composer

The Composer package stubbedev/jenkins-mcp is for PHP projects, or machines with PHP but no Node. It is a Composer plugin: on composer install / update it downloads the prebuilt binary for your OS and architecture (the same 14 targets as npm), from the release matching the installed version, so a pinned version pins the binary. Your MCP client then runs that native binary directly, and PHP is never in the request path:

composer require --dev stubbedev/jenkins-mcp      # per project
composer global require stubbedev/jenkins-mcp     # per user

Composer asks once whether to trust the plugin. For non-interactive installs (CI, provisioning), allow it up front:

composer config allow-plugins.stubbedev/jenkins-mcp true          # per project
composer global config allow-plugins.stubbedev/jenkins-mcp true   # per user

The install prints the binary's path. Point your client at it:

On Windows the binary is jenkins-mcp-native.exe. The PHP launcher works even if you declined the plugin: it downloads the binary on its first run (needs ext-curl or allow_url_fopen), then hands over to it. Clients start the server from their own working directory, so use absolute paths. Set JENKINS_MCP_SKIP_DOWNLOAD=1 to skip the install-time download.

Standalone binary (Go, Nix, release download)

go install github.com/stubbedev/jenkins-mcp@latest                    # → $GOBIN / $GOPATH/bin
nix run github:stubbedev/jenkins-mcp -- --config ~/.jenkins-mcp.json  # run straight from the flake

Or download jenkins-mcp_<os>_<arch> from the latest release, then chmod +x it (macOS/Linux/FreeBSD). The Nix flake can also be added as an input, using packages.default in your system/home configuration. It builds from source with buildGoModule; its version tracks package.json automatically and CI keeps the vendorHash current.

Updating

4. Connect to your AI tool

Each example shows the npx form first, then the form for an installed jenkins-mcp (npm global, Composer, Go, Nix or a release binary). With a per-project Composer install, use the absolute path to vendor/stubbedev/jenkins-mcp/bin/jenkins-mcp-native as the command.

Claude Code

# npx
claude mcp add jenkins -- npx -y @stubbedev/jenkins-mcp@latest --config ~/.jenkins-mcp.json

# installed (npm -g / Go / Nix / release binary)
claude mcp add jenkins -- "$(which jenkins-mcp)" --config ~/.jenkins-mcp.json

# Composer (global)
claude mcp add jenkins -- "$(composer global config home)/vendor/stubbedev/jenkins-mcp/bin/jenkins-mcp-native" --config ~/.jenkins-mcp.json

# Composer (per project, run from the project root)
claude mcp add jenkins -- "$PWD/vendor/stubbedev/jenkins-mcp/bin/jenkins-mcp-native" --config ~/.jenkins-mcp.json

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-only):

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["-y", "@stubbedev/jenkins-mcp@latest", "--config", "/Users/you/.jenkins-mcp.json"]
    }
  }
}

Installed via npm global, Composer, Go, Nix or a release binary, point command at the binary (which jenkins-mcp, or vendor/bin/jenkins-mcp for a per-project Composer install):

{
  "mcpServers": {
    "jenkins": {
      "command": "/Users/you/.composer/vendor/bin/jenkins-mcp",
      "args": ["--config", "/Users/you/.jenkins-mcp.json"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["-y", "@stubbedev/jenkins-mcp@latest", "--config", "/Users/you/.jenkins-mcp.json"]
    }
  }
}

Installed via npm global, Composer, Go, Nix or a release binary, point command at the binary (which jenkins-mcp, or vendor/bin/jenkins-mcp for a per-project Composer install):

{
  "mcpServers": {
    "jenkins": {
      "command": "/Users/you/.composer/vendor/bin/jenkins-mcp",
      "args": ["--config", "/Users/you/.jenkins-mcp.json"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "jenkins": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/jenkins-mcp@latest", "--config", "/home/you/.jenkins-mcp.json"]
      }
    }
  }
}

Installed via npm global, Composer, Go, Nix or a release binary:

{
  "context_servers": {
    "jenkins": {
      "command": {
        "path": "/home/you/.config/composer/vendor/bin/jenkins-mcp",
        "args": ["--config", "/home/you/.jenkins-mcp.json"]
      }
    }
  }
}

OpenCode

Add to opencode.json in your project root (or ~/.config/opencode/opencode.json for global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jenkins": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/jenkins-mcp@latest", "--config", "/home/you/.jenkins-mcp.json"]
    }
  }
}

Installed via npm global, Composer, Go, Nix or a release binary:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jenkins": {
      "type": "local",
      "command": ["/home/you/.config/composer/vendor/bin/jenkins-mcp", "--config", "/home/you/.jenkins-mcp.json"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.yaml:

mcpServers:
  jenkins:
    command: npx
    args:
      - -y
      - @stubbedev/jenkins-mcp@latest
      - --config
      - /home/you/.jenkins-mcp.json

Installed via npm global, Composer, Go, Nix or a release binary:

mcpServers:
  jenkins:
    command: /home/you/.config/composer/vendor/bin/jenkins-mcp
    args:
      - --config
      - /home/you/.jenkins-mcp.json

Any other MCP-compatible tool

Most tools that support MCP accept the same JSON format. Use npx as the command with ["-y", "@stubbedev/jenkins-mcp@latest", "--config", "/path/to/config.json"] as the args, or the installed jenkins-mcp (absolute path) as the command with ["--config", "/path/to/config.json"].

Manual install (optional)

If you prefer to clone and build locally (requires Go 1.26+):

git clone git@github.com:stubbedev/jenkins-mcp.git
cd jenkins-mcp
go build -o jenkins-mcp .

Then use /path/to/jenkins-mcp/jenkins-mcp as the command in the configs above.

Output format (TOON)

Structured tool responses (jenkins_get_job_config, and the config echoed back by jenkins_update_job_config) are serialized as TOON (Token-Oriented Object Notation) by default — a compact, LLM-friendly format that uses fewer tokens than equivalent JSON. Pass format: "json" on those tools to get JSON instead, or set JENKINS_MCP_FORMAT=json to flip the default process-wide. The build/log/test/queue tools already return purpose-built plain text and are unaffected.

Transport: stdio (default) or HTTP

By default the server speaks MCP over stdio — the right choice when your AI tool launches the binary as a child process (the configs above).

To run it as a long-lived service — e.g. shared by a team, or sitting behind a reverse proxy — start it in Streamable HTTP mode instead:

jenkins-mcp --http                 # listen on 127.0.0.1:8080/mcp
jenkins-mcp --http 0.0.0.0:9000    # bind a specific addr/port
JENKINS_MCP_HTTP=:8080 jenkins-mcp # same, via env (handy in containers)

Point your MCP client at http://<host>:<port>/mcp. Put TLS/auth on the proxy in front; the server itself does not terminate TLS.

The HTTP server is stateful by default: it keeps a session per client so server→client requests work — namely the MCP roots lookup used to find the caller's repo, and the elicitation prompt that disambiguates when a repo maps to multiple Jenkins jobs. This is the right default for a local proxy (single tenant — nothing to load-balance).

If you front it with a cloud load balancer, pass --http-stateless: every request becomes self-contained with no session affinity to pin. The trade-off is that roots resolution and the elicitation picker no longer work — supply the repo root via header/arg and pass jobPath explicitly.

Working directory in HTTP mode

In stdio mode the server runs git in its own working directory to auto-resolve jobPath from the current repo's remote (via repoJobMap). Over HTTP there is no single working tree — the process serves many callers — so the working tree is resolved per request, checked in this order:

1. cwd (or repoRoot) tool argument — supply the repo root on the call; git runs there for that request.

2. X-Repo-Root (or X-Cwd) HTTP header — a fronting proxy/harness can inject the repo root per request.

3. MCP roots — if the client exposes its workspace via the roots capability, git runs there. With several roots, the server runs git in each and unions the repoJobMap matches, so the one root that maps to a Jenkins job wins automatically; if several roots map to different jobs you get the elicitation picker. Cached per session and refreshed on roots/list_changed (stateful mode only).

If none of these yields a repo (e.g. stateless mode with no header, or no root maps), pass jobPath explicitly. Errors name the resolved directory (e.g. "ran git in /x but found no origin remote") so misconfiguration is obvious.

Operational notes (HTTP)

• Health check: GET /healthz returns 200 ok jenkins-mcp <version> — wire it to your proxy/orchestrator liveness probe.

• Graceful shutdown: SIGINT/SIGTERM drains in-flight requests (5s) before exiting.

• Session reaping: stateful sessions idle longer than 30 min are dropped, so a long-lived server doesn't leak state from clients that disconnected uncleanly.

• No hangs: git invocations run with GIT_TERMINAL_PROMPT=0 and a 10s timeout; the roots/list lookup has a 5s timeout. A wedged client or repo can't stall a tool call.

Notes

• Authentication is HTTP Basic with username:apitoken (Jenkins's standard mechanism).

• Write operations (jenkins_trigger_build, jenkins_stop_build, jenkins_update_job_config) require the API token user to have the appropriate Jenkins permissions.

• CSRF crumb handling is automatic — API tokens bypass the crumb check on most Jenkins installations, but the server fetches and caches a crumb for installations that require it.

• jenkins_get_build with sha scans the last 30 builds of the job for a matching lastBuiltRevision. Increase scanLimit for repos with many builds per commit.

• Pipeline stage breakdown comes from Jenkins's wfapi (workflow plugin). Freestyle jobs don't expose it, and the tool falls back to summary fields only.

• Test reports come from the standard Jenkins JUnit / xUnit plugins. Jobs that don't publish results return a friendly 404 message.

Releases (Maintainers)

Each release ships prebuilt Go binaries (attached to the GitHub release), the npm wrapper @stubbedev/jenkins-mcp, and the Composer package stubbedev/jenkins-mcp. .github/workflows/publish.yml runs on a pushed v* tag and: cross-compiles binaries for 14 targets — linux (amd64, arm64, arm/v7, 386, ppc64le, s390x, riscv64), darwin (amd64, arm64), windows (amd64, arm64, 386), and freebsd (amd64, arm64) — attaches them to the GitHub release, then publishes the npm package. The Nix flake builds from the tagged source and tracks package.json for its version, so it needs no separate release step.

Use semantic versioning. Breaking tool-surface changes should bump the minor version while <1.0.0 (for example 0.0.x -> 0.1.0).

Release flow (the preversion hook runs go vet, go test, and the smoke check first):

# choose one: patch | minor | major
npm run release:minor

This bumps package.json, commits, tags, and pushes; the pushed tag drives the publish workflow.

• The npm step uses npm Trusted Publisher (OIDC), so no NPM_TOKEN secret is required

• The release step uses the default GITHUB_TOKEN

Required npm setup (one-time):

• In npm package settings, add this GitHub repo/workflow as a Trusted Publisher

Packagist needs no workflow step: it reads composer.json straight from each pushed v* tag (no version field, since the tag is the version, and the launcher reads package.json to pick the release binary). One-time setup: submit the repo at https://packagist.org/packages/submit and keep the Packagist GitHub integration enabled so new tags are picked up automatically.

Development

Requires Go 1.26+. Dependencies: modelcontextprotocol/go-sdk (official MCP SDK), toon-format/toon-go (TOON output), and beevik/etree (lossless config.xml editing).

# Build
go build -o jenkins-mcp .

# Run directly
./jenkins-mcp --config /path/to/config.json

# Vet + test
go vet ./...
go test ./...

# Quick smoke check (builds + validates tools/list)
npm run smoke

# Test the tool list by hand
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | ./jenkins-mcp

Tool schemas live in tools.json (embedded into the binary via go:embed). The npm wrapper lives in bin/cli.mjs + scripts/; the Composer plugin is src/ComposerPlugin.php, with the launcher bin/jenkins-mcp (PHP) and the download logic both share in src/Binary.php. All of them download the release binary to bin/jenkins-mcp-native. The Nix flake is flake.nix.