Jenkins MCP Server

Production-ready Jenkins Model Context Protocol server for Hermes Agent and other MCP clients.

Tools

23 tools, grouped as the guardrail policy groups them.

See Security and guardrails for how to restrict these at either layer.

Related MCP server: MCP-Jenkins

Jenkins compatibility

"Verified" means the full end-to-end suite ran against that core in CI: create a Pipeline job, trigger it, stream the console, stop the build, delete the job, with all 23 tools reachable. Reproduce any row with compatibility.yml.

Run the current LTS line where possible: it is the only line receiving security backports.

Requirements

A missing plugin disables the tools that depend on it. The rest, including all freestyle and node tools, continue to work on a core-only controller.

Known issues

Plugin, permission, proxy and scale details, and how to verify against your own controller, are in docs/JENKINS_COMPATIBILITY.md.

Capabilities

• Native MCP Streamable HTTP endpoint at /mcp and optional stdio transport.

• Job list/read/create/update/delete/copy/enable/disable.

• Pipeline and Git multibranch Pipeline creation and scanning.

• Build trigger, parameterized builds, running-build discovery, stop/terminate/kill.

• Queue inspection and cancellation.

• Node inspection and optional online/offline management.

• Progressive bounded console logs.

• Jenkins crumb support, retries, timeouts, nested-folder paths, and TLS verification.

• Read-only mode, job allowlist, write-category controls, and JSONL audit logging.

• Optional generic administrator REST request, disabled by default.

Published artifacts

ghcr.io/grglzrv/jenkins-mcp-server:<version>
ghcr.io/grglzrv/jenkins-mcp-server:<version>-minibridge
oci://ghcr.io/grglzrv/charts/jenkins-mcp-server --version <version>

Release images are published for linux/amd64 and linux/arm64. The plain image contains only the Python server. The -minibridge tag is a separately built variant that bundles both executables in one container; Minibridge is not a sidecar and is not downloaded at pod startup.

Architecture

Requests pass through up to two independent enforcement layers before reaching Jenkins. The server's own policy always applies. The minibridge proxy is optional and adds a second layer in front of it.

Inside minibridge the three settings do different jobs, which is easy to confuse because they sit side by side in values.yaml:

minibridge is the component; guardrails is one key inside it. With minibridge.enabled: false the guardrails list does nothing, because there is no proxy to evaluate it.

The deployment path in the reference Kubernetes setup:

Hermes Agent
    │ HTTPS over Tailscale
    ▼
Tailscale Kubernetes Ingress
    │
    ▼
Jenkins MCP Server /mcp
    │ HTTPS through Tailscale egress
    ▼
Jenkins controller

Hermes never receives the Jenkins API token. The token stays in a Kubernetes Secret or external secret provider and is used only by the MCP server.

Quick start with Docker

cp .env.example .env
# Configure Jenkins URL, username, token, and CA bundle.

docker build --build-arg APP_VERSION=$(cat VERSION) \
  -t jenkins-mcp-server:$(cat VERSION) .

docker run --rm \
  --env-file .env \
  -p 8000:8000 \
  -p 8081:8081 \
  -v "$PWD/certs:/certs:ro" \
  jenkins-mcp-server:$(cat VERSION)

Or use the maintained Compose deployment, which applies a read-only root filesystem, dropped capabilities, writable temporary mounts, and an audit volume:

cp .env.example .env
# Edit .env, keep it out of source control, and restrict its permissions.
docker compose up server

# Run the single-container Minibridge variant instead. Its sample policy
# allows every non-destructive tool and refuses @destructive.
docker compose --profile minibridge up minibridge

Do not start both services together because they publish the same MCP port.

Health endpoints:

GET http://localhost:8081/healthz
GET http://localhost:8081/readyz

MCP endpoint:

http://localhost:8000/mcp

Helm installation

kubectl create namespace jenkins-mcp
kubectl -n jenkins-mcp create secret generic jenkins-mcp-secrets \
  --from-literal=JENKINS_USERNAME=hermes-jenkins \
  --from-literal=JENKINS_TOKEN='<JENKINS_API_TOKEN>'

helm upgrade --install jenkins-mcp \
  oci://ghcr.io/grglzrv/charts/jenkins-mcp-server \
  --version 1.23.0 \
  --namespace jenkins-mcp \
  --values examples/values/tailscale-production.yaml

The chart includes hardened pod settings, probes, NetworkPolicy, PodDisruptionBudget, optional External Secrets, Tailscale ingress, and Tailscale egress to Jenkins. Credentials can come from one existing Secret, separate username and token Secret references, a chart-managed development Secret, or External Secrets Operator. See per-field-secret-refs.yaml for the split-secret form.

For strict TLS, configure jenkins.url with Jenkins's exact Tailscale MagicDNS FQDN and route the tailnet DNS zone through the Operator DNSConfig; do not use the Kubernetes egress Service name as the HTTPS hostname.

Connecting a client

The server speaks Streamable HTTP. Point any MCP client at the /mcp path of whichever address exposes it; the exact configuration keys differ per client, so use its own documentation for the surrounding structure.

The Helm chart derives the Service name from the release, so a release named jenkins-mcp in namespace jenkins-mcp gives jenkins-mcp-jenkins-mcp-server.jenkins-mcp.svc.cluster.local. Read it back rather than assuming:

kubectl -n <namespace> get svc -l app.kubernetes.io/name=jenkins-mcp-server \
  -o jsonpath='{.items[0].metadata.name}'

With an ingress, the controller assigns the hostname asynchronously:

kubectl -n <namespace> get ingress -l app.kubernetes.io/name=jenkins-mcp-server \
  -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}'

Whichever client you use, it never receives the Jenkins API token. The token stays in a Kubernetes Secret and is used only by this server.

Security and guardrails

Two layers, applied independently.

Layer 1 — server policy (mcp.*), always enforced

Enforced inside the Python process. It applies whether or not minibridge is deployed, and cannot be bypassed by a client.

JENKINS_VERIFY_TLS=true
MCP_READ_ONLY=false
MCP_ALLOW_JOB_WRITE=true
MCP_ALLOW_BUILD_WRITE=true
MCP_ALLOW_NODE_WRITE=false
MCP_ALLOW_ADMIN_REQUEST=false
MCP_ALLOWED_JOBS=AI/*,Platform/*

Destructive actions are gated separately from ordinary writes, so an agent can create and trigger jobs while never being able to delete one. Each destructive action must clear its category flag, the master switch, and its own flag.

To disable every irreversible action at once while keeping reads, job creation and build triggering:

mcp:
  allowDestructive: false

MCP_READ_ONLY=true overrides everything, and MCP_ALLOWED_JOBS restricts every tool to matching job paths. Job names containing . or .. segments are rejected at both the policy and URL layers.

Layer 2 — minibridge proxy (optional)

Minibridge terminates MCP over HTTP, evaluates a Rego policy on every request and response, and speaks stdio to the server it spawns. It requires the -minibridge image built from docker/Dockerfile.minibridge.

minibridge:
  enabled: true

The chart selects ghcr.io/grglzrv/jenkins-mcp-server:<version>-minibridge, published alongside the default image on every release. edge-minibridge tracks main. The chart runs one container: its entrypoint starts Minibridge, which spawns jenkins-mcp-server --transport stdio. Minibridge v0.8.0 is checksum-pinned rather than fetched from latest, since a proxy in the request path should not change enforcement behaviour on an unrelated rebuild.

Credential injection is unchanged with the proxy on or off: JENKINS_TOKEN always arrives via secretKeyRef from a Kubernetes Secret, which External Secrets can populate from GCP Secret Manager.

Disabling destructive tools and capabilities

minibridge.tools is a policy over the server's whole tool surface. The default is allow-all — with both lists empty every tool and capability is permitted, and restriction is entirely opt-in.

Entries are a bare tool name or a group:

Exclude only the irreversible tools, keeping everything else:

minibridge:
  enabled: true
  tools:
    deny: ["@destructive"]

A strict read-only deployment — a non-empty allow becomes an allowlist:

minibridge:
  tools:
    allow: ["@read"]

deny always wins over allow. Denied tools are refused on tools/call and filtered out of tools/list, so the agent never sees a tool it cannot use. Whole MCP capabilities are gated by method name:

minibridge:
  methodsDeny: ["resources/read"]

Every one of the 23 tools belongs to exactly one group, asserted by a test so the groups cannot drift from the server.

Guardrails

Heuristic content inspection, independent of the tool policy above. All are off by default; enable only what you need.

minibridge:
  guardrails:
    - secrets-redaction
    - sensitive-pattern-detection
    - covert-instruction-detection

The policy has 29 OPA tests covering both directions — that clean console output and this server's own tool names are not flagged, and that injection, traversal and token leakage are. They run in CI via the policy job.

Shared-secret authentication

A lightweight auth layer checked by the policy against the Authorization header. The secret is referenced from a Kubernetes Secret and never inlined in values:

minibridge:
  basicAuth:
    enabled: true
    existingSecret: jenkins-mcp-server-credentials
    secretKey: BASIC_AUTH_SECRET

If that Secret is managed by External Secrets, add the key to externalSecret.extraData — otherwise the chart fails the render with an explanation rather than producing a pod that cannot start.

Use it only in controlled environments, rotate the secret, and always pair it with TLS (minibridge.tls, which also supports mTLS via clientCASecretKey).

Enforcement

minibridge:
  policer:
    enforce: true          # false logs the verdict and lets traffic through
    rego:
      enabled: true
      policy: /policy.rego
    http:
      enabled: false       # or delegate to a remote HTTP policer
      url: ""
      token:
        existingSecret: ""
        secretKey: MINIBRIDGE_POLICER_HTTP_BEARER_TOKEN

The Rego and HTTP policers are mutually exclusive. For encrypted listener keys, minibridge.tls.passSecretKey reads the passphrase from the TLS Secret, while minibridge.tls.pass.valueFrom can reference a different Secret and key.

Recommended posture

Use a dedicated Jenkins service account. Keep jenkins_admin_request disabled unless there is a reviewed operational requirement, keep allowJobDelete: false, restrict MCP_ALLOWED_JOBS to controlled folders, and keep destructive tools behind human approval in the agent. Setting minibridge.tools.deny: ["@destructive", "@admin"] gives defence in depth: the proxy refuses the call and never advertises the tool, and the server would refuse it anyway.

Development

make install
make lint
make coverage
make verify-version

With Helm installed:

make helm-lint
make helm-template

Full Docker-based Jenkins TLS integration test:

make integration

Releases and versioning

One canonical semantic version is synchronized across the Python package, Helm chart, application image, and production Kustomize overlay. The chart is never left pointing at a stale image, because it does not pin an image tag at all:

image:
  repository: ghcr.io/grglzrv/jenkins-mcp-server
  tag: ""        # empty means use Chart.appVersion

So Chart.appVersion is the image tag. Bumping the version moves the chart and the image together by construction.

NEW_VERSION=1.23.0
make version VERSION="$NEW_VERSION"     # prepares notes and rewrites every pin
git commit -am "chore(release): prepare v$NEW_VERSION"
git push origin "release/v$NEW_VERSION"
# Open a PR and merge it after every required check is green.

make version rewrites all 22 managed application-version pins across 17 files: VERSION, pyproject.toml, src/jenkins_mcp_server/__init__.py, the chart's version and appVersion, both README install commands, the Kustomize base, production and minibridge overlays, the standalone minibridge deployment, the example values, Compose deployment, and all versioned Argo CD applications. scripts/check_version.py then asserts every declared pin exists exactly where expected and agrees. It additionally scans every small UTF-8 file in the repository, regardless of directory or extension, for application image tags, Helm install versions, Argo CD revisions, Kustomize tags, Compose defaults, and release examples. A newly added manifest or README with a stale version fails CI until it is added to the canonical pin inventory.

Before it rewrites a pin, make version promotes the completed [Unreleased] section in CHANGELOG.md to a dated version entry and recreates the empty template. Every release must explicitly cover highlights, new features, improvements, bug fixes, breaking changes, known issues, security, and upgrade notes. Use None or None known where appropriate; placeholders such as None yet, TBD, and TODO are rejected in a release entry. The GitHub Release publishes this validated entry verbatim instead of generating primary notes from commit titles.

When the validated version-change pull request merges to main, the release workflow starts automatically. It refuses to publish anything if these do not agree:

test "${version}" = "$(cat VERSION)"   # requested release must match VERSION
python scripts/check_version.py        # every versioned artifact must agree
python scripts/changelog.py validate   # release notes must be complete
python scripts/check_release_bump.py "$(git merge-base HEAD origin/main)"

The release-bump check covers application/package inputs, both runtime images, functional chart files, Compose, production manifests, Argo CD applications, and shipped values. It requires a strictly newer SemVer and reports every path that needs the release. Documentation, tests, integration fixtures, and workflow-only changes do not force a version bump.

Only after that gate passes does it build the multi-architecture image (tagged with the full version, major/minor, major, and latest), package the chart at the same version, push both to GHCR, and create the GitHub Release from the curated changelog entry with provenance and SBOM metadata.

A matching annotated tag can still trigger the same idempotent workflow as a manual recovery path. If the GitHub Release already exists, the run validates the version and source tag before safely skipping republication. Release runs are serialized so a recovery tag cannot race automatic publication.

Two consequences worth knowing:

• :edge never touches the chart. Every push to main publishes ghcr.io/grglzrv/jenkins-mcp-server:edge, but the chart only ever references appVersion. Edge images are opt-in via image.tag: edge.

• Chart-only changes still need a full version bump, since chart version and appVersion are deliberately locked together. That trades Helm's convention of versioning the chart independently for the guarantee that a chart version identifies exactly one application build.

Documentation

• Release process

• Jenkins compatibility: versions, plugins, permissions

• Tailscale: finding your domain and wiring it up

• Kubernetes, Tailscale, and Argo CD

• Helm chart

• Security model

Attribution

This is not an official Jenkins project. Jenkins is a registered trademark of the Continuous Delivery Foundation.