# jenkins-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Jenkins**, written in Go. Inspect builds, control jobs, and manage pipeline configuration — designed to pair with [`atlassian-mcp`](https://github.com/stubbedev/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](#3-install).

---

## Tools

### Inspection

| Tool | Description |
|---|---|
| `jenkins_get_build` | Status of a build by number, by SHA (auto-finds the build for a commit), or the latest. Includes Pipeline stage breakdown, parameters, changeset, and artifact URLs. |
| `jenkins_get_log` | Console log for a build. Pass `stageId` for just one Pipeline stage; defaults to a 200KB tail (use `full=true` to opt in to the entire log). |
| `jenkins_get_tests` | Test report — failing test names, classes, and stack traces. Far more useful than grepping the console log when a build fails. |
| `jenkins_list_builds` | Recent builds for a job, with result + duration + commit. |
| `jenkins_list_jobs` | Browse jobs at the root or inside a folder. |
| `jenkins_get_queue` | Items currently waiting in the build queue. |

### Build control

| Tool | Description |
|---|---|
| `jenkins_trigger_build` | Trigger a new build, optionally with parameters. Returns a queue item URL to track progress. |
| `jenkins_build_revision` | Build an exact commit on Git-plugin jobs through `/git/notifyCommit?sha1=`. For freestyle jobs with a wildcard branch spec, where a plain trigger rebuilds the last built revision. `url`, `branch` and `sha` default to the current repo, branch and `HEAD`. |
| `jenkins_stop_build` | Abort a running build by number. |

### Job configuration

| Tool | Description |
|---|---|
| `jenkins_get_job_config` | Fetch a job's configuration as a structured object (TOON by default) — pipeline definition, triggers, parameters, retention settings, and the SCM section (Git remotes with credential ids, never secrets; branch specs, flagged when parameterized). `buildRevision` says whether `jenkins_build_revision` will pin a commit on this job, and why not when it won't. |
| `jenkins_update_job_config` | Patch a job's configuration. Pass only the fields to change; everything else is preserved. Supports description, pipeline script/path, triggers, parameters, and build retention. `scm` and `buildRevision` are read-only, and unknown patch fields are rejected. |

### 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`
- "rebuild this commit now that CI is fixed" → `jenkins_build_revision`, then `jenkins_get_build` with `sha=<HEAD>`
- "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`

---

## 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`:

```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`).

Add `"notifyCommitToken": "<token>"` to use `jenkins_build_revision` on Git plugin 4.11 or later (see [Notes](#notes)).

Alternatively, use environment variables, or a `.env` file in the server's working directory. `.env` is read before any other setting, so it can also set the `JENKINS_MCP_*` options below; a variable already set in the environment wins. Each line is `KEY=value`; blank lines and `#` comments are allowed, quotes around a value are stripped, and any other line stops the server with the file name and line number:

```env
JENKINS_URL=https://jenkins.example.com
JENKINS_USERNAME=your-jenkins-login
JENKINS_TOKEN=your-api-token
JENKINS_NOTIFY_COMMIT_TOKEN=your-notifycommit-token   # optional
```

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. The first file found is used. A path given with `--config` or `JENKINS_MCP_CONFIG` must exist; the default locations are optional. A config file that cannot be read, is not valid JSON, or has keys outside the schema stops the server with the path and the reason. With no url, username and token at all the server starts unconfigured and says so; setting only some of them, or a url that is not a plain `http(s)://host[/path]` URL, stops it with what is wrong.

### 3. Install

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

| Option | Install | Command for your MCP client |
|---|---|---|
| **npx** (Node 24+) | nothing, fetched on first run | `npx -y @stubbedev/jenkins-mcp@latest` |
| **npm global** (Node 24+) | `npm install -g @stubbedev/jenkins-mcp` | `jenkins-mcp` |
| **Composer** (PHP 8.1+) | `composer global require stubbedev/jenkins-mcp` | the native binary it downloads — see [Composer](#composer) |
| **Composer, per project** | `composer require --dev stubbedev/jenkins-mcp` | `vendor/stubbedev/jenkins-mcp/bin/jenkins-mcp-native` |
| **Prebuilt binary** | download `jenkins-mcp_<os>_<arch>` from the [latest release](https://github.com/stubbedev/jenkins-mcp/releases/latest) | path to that file |
| **Go** | `go install github.com/stubbedev/jenkins-mcp@latest` | `jenkins-mcp` (in `$GOBIN`) |
| **Nix** | `nix profile install github:stubbedev/jenkins-mcp` | `jenkins-mcp` |

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`.

```bash
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 13 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:

```bash
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:

```bash
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:

| Install | Native binary (no PHP at runtime) | PHP launcher |
|---|---|---|
| per project | `vendor/stubbedev/jenkins-mcp/bin/jenkins-mcp-native` | `vendor/bin/jenkins-mcp` |
| per user | `$(composer global config home)/vendor/stubbedev/jenkins-mcp/bin/jenkins-mcp-native` | `$(composer global config bin-dir --absolute)/jenkins-mcp` |

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` (or `true`) to skip the install-time download; any value other than 1, true, 0 or false is an error.

#### Binary cache

npm and Composer download each release's binary once per user, verify it against the
release's `checksums.txt`, and keep it in `$XDG_CACHE_HOME/jenkins-mcp/<version>/` (by
default `~/.cache` on Linux and FreeBSD, `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on
Windows), and hardlink it into every install, or copy it where the install is on another
filesystem. Further projects and git worktrees on the same version install without
downloading anything. Delete old version directories to reclaim their space; installs keep
their own link.

#### Standalone binary (Go, Nix, release download)

```bash
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](https://github.com/stubbedev/jenkins-mcp/releases/latest), 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

| Option | Update |
|---|---|
| npx | `npx clear-npx-cache`, then restart your MCP client |
| npm global | `npm update -g @stubbedev/jenkins-mcp` |
| Composer | `composer global update stubbedev/jenkins-mcp` (or `composer update stubbedev/jenkins-mcp` in the project) |
| Go / Nix / binary | re-run the install command or download the newer release |

### 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

```bash
# 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):

```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):

```json
{
  "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`:

```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):

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

---

#### Zed

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

```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:

```json
{
  "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):

```json
{
  "$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:

```json
{
  "$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`:

```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:

```yaml
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+):

```bash
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](https://github.com/toon-format/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:

```bash
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)
```

| Flag / env | Effect |
| --- | --- |
| `--http[=addr]` / `--http addr` | Enable HTTP. `addr` defaults to `127.0.0.1:8080`. |
| `JENKINS_MCP_HTTP=addr` | Enable HTTP via env. `1`/`true` means the default addr. |
| `JENKINS_MCP_HTTP_PATH=/path` | Endpoint path (default `/mcp`). |
| `--http-stateless` / `JENKINS_MCP_HTTP_STATELESS=1` | Drop persistent sessions (see below). |

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](https://modelcontextprotocol.io/docs/concepts/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).
- Tool arguments are validated against each tool's input schema in `tools.json`, which is also where defaults and limits live. A wrong type (`full: "true"`), an out-of-range number, an empty string, an unknown argument or a typo in a patch field is rejected with the argument name and the value sent, instead of being coerced or ignored. `job` and `repoRoot` are aliases for `jobPath` and `cwd`; passing both forms is an error.
- Write operations (`jenkins_trigger_build`, `jenkins_build_revision`, `jenkins_stop_build`, `jenkins_update_job_config`) require the API token user to have the appropriate Jenkins permissions.
- `jenkins_build_revision` calls the Git plugin's `notifyCommit` endpoint, which schedules a build of the given `sha1` on every job whose remote matches `url` and whose branch spec matches `branch`, and which has **Poll SCM** enabled (an empty schedule is enough). Since Git plugin 4.11 the endpoint needs its own access token: create one under **Manage Jenkins → Security → Git plugin notifyCommit access tokens** and set it as `notifyCommitToken` in the config file (or `JENKINS_NOTIFY_COMMIT_TOKEN`).
- 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` (1-200) for repos with many builds per commit. When nothing matches, the reply says how many builds were scanned and whether that was every build the job still retains or the `scanLimit` bound.
- 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 13 targets — linux (amd64, arm64, arm/v7, 386, ppc64le, s390x, riscv64), darwin (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):

```bash
# 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`](https://github.com/modelcontextprotocol/go-sdk) (official MCP SDK), [`toon-format/toon-go`](https://github.com/toon-format/toon-go) (TOON output), and [`beevik/etree`](https://github.com/beevik/etree) (lossless config.xml editing).

```bash
# 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`, with the package in `nix/package.nix` and the dev shell in `nix/shell.nix`.