jenkins-mcp

Jenkins MCP

A single-file MCP server that exposes a Jenkins instance (plus a thin GitLab layer) as tools an LLM can call. It lets Claude Code — or any MCP client — list jobs, trigger and watch deployments, read build logs, and answer "is this ticket deployed yet?" without anyone touching the Jenkins UI.

Built on FastMCP from the mcp SDK. Python ≥ 3.10. One module: server.py.

What it can do

The tools are layered — higher tiers compose the lower ones.

Low-level Jenkins

Tool	Purpose
`list_jobs`	List jobs (with status) at the root or in a folder
`get_job_info`	Job details: parameters (with defaults/types), last build numbers, health
`trigger_build`	Start a build with raw Jenkins parameter names
`get_queue` / `get_queue_item`	Inspect the build queue
`wait_for_build`	Block until a queued item gets a build number
`get_build_info`	Result, timestamp, duration, parameters, git revision of a build
`get_build_log`	Console output (tail) for a build
`list_recent_builds`	Recent builds for a job
`get_last_successful_build`	Last green build of a job
`is_deployed_since`	Did a build run after a given timestamp?

High-level deploy (friendly args → whatever raw params the job actually defines)

Tool	Purpose
`deploy`	Deploy a job by `branch` / `tickets`, etc. Maps friendly names to real Jenkins params. A bare environment defaults to the configured app job (`dev` → `dev_app_deployment`; say `dev backend` for the backend job). Accepts multiple comma-separated ticket URLs. Refuses to deploy a job that mandates a deployment purpose until one is supplied (or `use_dummy_purpose=True`), and warns if a supplied URL is a merge request rather than a ticket (override with `allow_mr_purpose=True`).
`deploy_tickets`	Deploy by environment + scope from a set of ticket URLs
`list_deployments`	The configured `(env, scope) → job` table
`resolve_job_name`	Fuzzy-resolve a rough name (`"dev backend"`) to the real job

GitLab ticket verification

Tool	Purpose
`get_ticket_mrs`	Find MRs linked to a ticket
`is_ticket_deployed`	Check whether a ticket's merge commits are in the deployed branch tip

Prerequisites

Python ≥ 3.10
Network access to your Jenkins controller (and to your GitLab instance for the ticket tools)
A Jenkins API token (Jenkins → user → Configure → API Token)
A GitLab access token with read_api on the relevant project (only needed for the ticket-deployment tools)

Configuration

Two pieces: credentials in .env, and your site's job mapping in config.json.

Credentials

Copy the template and fill it in. .env is git-ignored — never commit it.

cp .env.example .env

Variable	Required	Notes
`JENKINS_URL`	yes	e.g. `https://jenkins.example.com`
`JENKINS_USER`	yes	Your Jenkins username
`JENKINS_TOKEN`	yes	Jenkins API token (not your password)
`GITLAB_URL`	for GitLab tools	e.g. `https://gitlab.example.com`
`GITLAB_PROJECT`	for GitLab tools	e.g. `your-group/your-project`
`GITLAB_TOKEN`	for GitLab tools	Falls back to a token found in `~/.claude.json` if unset
`JENKINS_MCP_CONFIG`	no	Path to the job mapping. Defaults to `./config.json`
`MCP_TRANSPORT`	hosted mode	`stdio` (default) or `streamable-http`
`MCP_HOST` / `MCP_PORT`	hosted mode	Defaults `0.0.0.0` / `8765`
`MCP_AUTH_TOKEN`	hosted mode	Shared bearer token for the HTTP endpoint. Set this when running HTTP — without it the endpoint is unauthenticated and the server logs a warning

Generate a bearer token with:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Job mapping

The Jenkins tools are generic. The deploy tools need to know your job names and the parameter names those jobs define:

cp config.example.json config.json    # then edit; config.json is git-ignored

env_jobs maps "<environment>/<scope>" to a Jenkins job name; param_map maps friendly argument names to the raw Jenkins parameters to set. Without a config file the low-level Jenkins tools still work and deploy reports that no mapping is configured.

Setup A — local (stdio)

Run the server as a subprocess your MCP client spawns over stdio. Simplest for single-user use.

python3 -m venv .venv
./.venv/bin/pip install -e .
cp .env.example .env             # then edit
cp config.example.json config.json   # then edit
./.venv/bin/python server.py     # smoke test — Ctrl-C to stop

Register it with your MCP client. For Claude Code, add to .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "jenkins-mcp": {
      "command": "/absolute/path/to/jenkins-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/jenkins-mcp/server.py"]
    }
  }
}

Leave MCP_TRANSPORT unset (defaults to stdio). The .env beside server.py supplies the credentials.

Setup B — hosted (HTTP), shared by a team

Run it as a systemd service so everyone's client talks to one shared instance instead of each person running their own.

git clone <your-fork-url> jenkins-mcp
cd jenkins-mcp
cp .env.example .env                 # set JENKINS_*, GITLAB_*, MCP_TRANSPORT, MCP_AUTH_TOKEN
cp config.example.json config.json   # set your job mapping
bash deploy/install.sh               # venv, systemd unit, start

deploy/install.sh is idempotent: it builds .venv, installs the package, copies deploy/jenkins-mcp.service to /etc/systemd/system/, enables it and starts it. Edit the unit's User and paths to suit your host — it ships pointing at /opt/jenkins-mcp.

For HTTP mode your .env needs:

MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=8765
MCP_AUTH_TOKEN=<token from secrets.token_urlsafe(32)>

Bind to 127.0.0.1 and front it with a reverse proxy if the host is reachable beyond your trusted network.

Client config for the hosted server

{
  "mcpServers": {
    "jenkins-mcp": {
      "type": "http",
      "url": "http://your-server:8765/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Updating a hosted instance

The host runs from a git clone, so updates are pull-and-restart:

cd ~/jenkins-mcp
git pull
./.venv/bin/pip install -e .      # only if dependencies changed
sudo systemctl restart jenkins-mcp.service
journalctl -u jenkins-mcp -f      # watch it come back up

Tests

./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q

The suite covers CSRF crumb caching and 403 retry, deploy-target resolution, the deployment-purpose gate, and the pure helpers. It runs without a live Jenkins.

Notes

Jenkins ties each CSRF crumb to a session, so all traffic goes through one requests.Session. A 403 on POST is retried exactly once with a fresh crumb.
Job names are resolved with an exact → normalized → substring → close-match cascade against a 60-second-cached job list.
deploy refuses to run a job whose DEPLOYMENT_PURPOSE parameter is a validating string until a purpose is supplied, and warns when the supplied URL looks like a merge request rather than a ticket.

License

MIT — see LICENSE.