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

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

GitLab ticket verification

Related MCP server: MCP-Jenkins

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

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.