Skip to main content
Glama

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


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

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.

Available Tools

17 tools
deployA

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_deployment can cover

    • BE changes: <env>_app_deployment or <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

    A3.6/5.0

    Scored across 17 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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
    • A
      license
      B
      quality
      C
      maintenance
      A 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.
      11
      500 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enterprise-grade MCP server for Jenkins CI/CD integration that enables AI assistants to diagnose build failures, analyze pipelines, and search logs through natural conversation.
      6
      GPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents and external systems to programmatically trigger and monitor Jenkins jobs, retrieve build status and logs via MCP standards.
      -