jenkins-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jenkins-mcp Deploy the backend job to production"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 (with status) at the root or in a folder |
| Job details: parameters (with defaults/types), last build numbers, health |
| Start a build with raw Jenkins parameter names |
| Inspect the build queue |
| Block until a queued item gets a build number |
| Result, timestamp, duration, parameters, git revision of a build |
| Console output (tail) for a build |
| Recent builds for a job |
| Last green build of a job |
| Did a build run after a given timestamp? |
High-level deploy (friendly args → whatever raw params the job actually defines)
Tool | Purpose |
| Deploy a job by |
| Deploy by environment + scope from a set of ticket URLs |
| The configured |
| Fuzzy-resolve a rough name ( |
GitLab ticket verification
Tool | Purpose |
| Find MRs linked to a ticket |
| Check whether a ticket's merge commits are in the deployed branch tip |
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_apion 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 .envVariable | Required | Notes |
| yes | e.g. |
| yes | Your Jenkins username |
| yes | Jenkins API token (not your password) |
| for GitLab tools | e.g. |
| for GitLab tools | e.g. |
| for GitLab tools | Falls back to a token found in |
| no | Path to the job mapping. Defaults to |
| hosted mode |
|
| hosted mode | Defaults |
| 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-ignoredenv_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 stopRegister 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, startdeploy/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 upTests
./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -qThe 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.
deployrefuses to run a job whoseDEPLOYMENT_PURPOSEparameter 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.
Available Tools
17 toolsdeployA
High-level deploy. Maps friendly args to the job's actual Jenkins parameters.
Args:
job: Deploy target (fuzzy). A bare environment defaults to the configured app job:
'dev' / 'deploy dev' → 'dev_app_deployment'; say 'dev backend' for the
backend job. Other job names resolve by fuzzy match.
branch: Git branch to deploy. Sets whichever branch parameter the job defines (see config).
tickets: Ticket URL(s) for the deployment purpose. Multiple URLs may be passed
comma-separated ('url1, url2'); they are normalized to a comma-joined list.
install_dependencies: If True, sets INSTALL_BE_REQUIREMENTS + INSTALL_FE_PACKAGES (whichever exist).
use_server_secrets: Sets USE_SECRETS_FROM_SERVER.
config_branch: Sets CONFIGURATION_MANAGEMENT_BRANCH. Default is already 'main' on most jobs.
use_dummy_purpose: When the job mandates a deployment purpose and the user has no
ticket URL, set this True to deploy with the placeholder purpose
(<configured dummy_purpose>). Leave False to be told the purpose is required.
allow_mr_purpose: Set True to accept a merge-request URL as the purpose after the
user confirms (see the 'mr_url_as_purpose' guard below).
extra: Raw Jenkins param overrides {name: value}. Used for anything the friendly API misses.
wait: Poll the queue until a build number is assigned.
timeout: Max seconds to wait for the queue→build transition.
Mandatory deployment purpose: if the resolved job enforces a non-empty purpose
(DEPLOYMENT_PURPOSE) and no tickets was given, this returns
{"error": "deployment_purpose_required", ...} WITHOUT deploying. When you get
that, ask the user whether to (a) paste a ticket/URL — then re-call with tickets=...
— or (b) proceed with a dummy URL — then re-call with use_dummy_purpose=True.
Merge-request URL guard: the purpose should be ticket URL(s). If any supplied URL is a
merge request (/merge_requests/<id>) this returns {"error": "mr_url_as_purpose", ...}
WITHOUT deploying. Tell the user the URL is an MR, not a ticket, and ask them to either
paste the correct ticket URL or re-call with allow_mr_purpose=True to proceed anyway.
Returns the trigger result with build_number, build_url, and parameters_sent.
Inputs: job (required), wait, extra, branch, +7 more.
deploy_ticketsA
One-shot deploy by ticket URL(s) + environment.
Use when the user says things like:
"deploy on dev"
"deploy , to stage"
"deploy on dev backend"
Args: tickets: Ticket URL, or multiple URLs (comma, semicolon, or whitespace-separated). environment: 'dev' / 'stage' (aliases: 'development', 'staging', 'stg'). scope: 'app' (combined FE+BE, default) or 'backend' (backend-only). branch: Optional git branch override. If omitted, Jenkins uses the job's default ('dev' for dev jobs, 'stage' for stage jobs). install_dependencies: Optional override for INSTALL_BE_REQUIREMENTS / INSTALL_FE_PACKAGES. wait: Poll the queue until a build number is assigned. timeout: Max seconds to wait for the queue→build transition.
Inputs: tickets (required), environment (required), wait, scope, +4 more.
get_build_infoB
Full info about a specific build: result, timestamp, duration, parameters, git.
Inputs: job_name (required), build_number (required).
get_build_logB
Console output for a build. Returns the last tail_lines lines by default.
Inputs: job_name (required), build_number (required), tail_lines.
get_job_infoA
Get details about a job: description, parameters (with defaults), last build numbers, health.
Inputs: job_name (required).
get_last_successful_buildA
Last SUCCESSFUL build with timestamp, duration, parameters, and git info.
Primary use case: compare timestamp vs a GitLab MR merge time to verify deployment.
Inputs: job_name (required).
get_queueA
List items currently waiting in the build queue.
Inputs: no named parameters. Returns: result
get_queue_itemA
Poll a single queue item URL — returned by trigger_build / deploy when wait=False.
Inputs: queue_url (required).
get_ticket_mrsA
Find MRs linked to a ticket URL (matched in MR title/description).
Args: ticket_url: Full URL of the GitLab ticket/issue. state: 'all' | 'opened' | 'merged' | 'closed'. Default 'all'.
Inputs: ticket_url (required), state.
is_deployed_sinceA
Check whether the job's last successful build ran AFTER a given ISO timestamp.
Intended for: "was this GitLab MR (merged at <merge_time>) deployed?" Accepts ISO 8601 like '2026-04-24T10:15:00+00:00' or '2026-04-24T10:15:00Z'.
Inputs: job_name (required), merge_time_iso (required).
is_ticket_deployedA
Verify whether a ticket's merged MRs are deployed on dev or stage.
For each merged MR:
classifies files as frontend (frontend/, .scss/.css outside static/) or backend (static/**, requirements/, apps/, common/, hrdb/**, *.py)
checks if the MR's merge commit was an ancestor of the deployed branch at the time the relevant Jenkins build ran:
FE changes: only
<env>_app_deploymentcan coverBE changes:
<env>_app_deploymentor<env>_backend_deployment
reports per-MR deployed=true/false with reasons
Overall ticket is "deployed" only when every merged MR is fully covered. Un-merged MRs are reported separately.
Inputs: ticket_url (required), environment (required).
list_deploymentsA
List deployment-type jobs grouped by environment, with last build time + status.
Use this to discover what you can deploy. Returns groups: dev, stage, automation, utility, other.
Inputs: no named parameters.
list_jobsA
List Jenkins jobs. Pass folder (e.g. 'team/sub') to scope; empty lists root.
Inputs: folder. Returns: result
list_recent_buildsB
List recent builds for a job with timestamps, durations, and results.
Inputs: job_name (required), limit. Returns: result
resolve_job_nameA
Given a rough name ('dev backend'), show the matched job and close candidates.
Inputs: query (required).
trigger_buildA
Trigger a build with raw Jenkins parameter names.
If wait=True (default), polls the queue until a build number is assigned.
For a higher-level deploy with friendly names (branch, tickets…), use deploy().
Inputs: job_name (required), wait, timeout, parameters.
wait_for_buildA
Block polling a queue URL until a build number is assigned (or timeout).
Inputs: queue_url (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target distinct resources, but there is real overlap among queue-related tools (get_queue_item vs wait_for_build vs get_queue) and deploy helpers (deploy vs deploy_tickets vs trigger_build). The detailed descriptions help disambiguate, but some tools could still be confusing to an agent.
Tool names use consistent snake_case and mostly follow a verb_noun pattern: list_* and get_* for reads, trigger_build, deploy, resolve_job_name for actions. The mix of list/get and imperative verbs is minor and still predictable.
17 tools is slightly above the ideal 3-15 range, but the count is justified by combining core Jenkins introspection with deployment-specific and ticket-verification workflows. Each tool has a reasonably distinct niche.
The toolset covers job discovery, build triggering, queue monitoring, build results, logs, deployment configuration, and ticket-based deployment verification. Minor gaps such as cancel/abort build or job CRUD exist, but the core CI/CD and deployment workflows are well covered.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Devopness MCP server for DevOps happiness! Empower AI Agents to deploy apps and infra, to any cloud.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol (MCP) server that enables AI tools like chatbots to interact with and control Jenkins, allowing users to trigger jobs, check build statuses, and perform other Jenkins operations through natural language.MIT
- AlicenseBqualityCmaintenanceA server that enables interaction with Jenkins CI/CD pipelines from any compatible MCP client (like Claude Desktop), allowing users to manage jobs, builds, coverage reports, and other Jenkins functionality through natural language.11500 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnterprise-grade MCP server for Jenkins CI/CD integration that enables AI assistants to diagnose build failures, analyze pipelines, and search logs through natural conversation.6GPL 3.0
- FlicenseNot gradedqualityDmaintenanceEnables AI agents and external systems to programmatically trigger and monitor Jenkins jobs, retrieve build status and logs via MCP standards.-