Jenkins MCP Server

A production-ready Model Context Protocol server that exposes the Jenkins REST API as a rich set of structured tools, with first-class support for the jenkins-terraform-gcp:1.1 Docker image (Terraform + GCP aware log inspection).

Built with Python 3.13, FastMCP, requests and python-dotenv.

Features

• 64 MCP tools covering jobs, builds, pipelines, nodes, plugins, credentials, users, queue, views, search, system administration, Terraform and GCP.
• Folder, nested-folder, multibranch pipeline and organization-folder support.
• Automatic CSRF crumb handling (Crumb Issuer), with transparent retry on stale crumbs.
• Connection pooling + retry/backoff via a single shared requests.Session.
• Structured JSON responses: {"status": "success", "data": {...}, "message": "..."} / {"status": "error", "message": "..."}.
• Rotating file + console logging.
• Pagination support on list-style tools.
• Docker & docker-compose deployment.
• Optional Jenkins CLI fallback.

Project Structure

jenkins-mcp-gcp/
├── server.py            # FastMCP entry point - registers all tools
├── jenkins_client.py     # Jenkins REST API client (pooling, retries, crumb)
├── config.py             # .env-driven configuration
├── requirements.txt
├── .env.example
├── Dockerfile
├── docker-compose.yml
├── mcp.json              # Example MCP client configuration
├── tools/
│   ├── jobs.py           # Job management
│   ├── builds.py         # Builds, pipeline stages, queue, health report
│   ├── nodes.py          # Build agents / nodes
│   ├── plugins.py        # Plugin management
│   ├── credentials.py    # Credential metadata (no secrets)
│   ├── system.py         # Ping, system info, users, views, CLI
│   ├── terraform.py      # Terraform-aware tools
│   └── gcp.py            # GCP-aware tools
└── utils/
    ├── logger.py          # Logging configuration
    ├── helpers.py         # Response envelope, pagination, decorators
    └── terraform_parser.py  # Terraform/GCP log-parsing heuristics

Requirements

• Python 3.13+
• A running Jenkins instance (the jenkins-terraform-gcp:1.1 image at http://localhost:8090 by default)
• A Jenkins API token (Jenkins → your user → Configure → API Token → Add new Token)

Installation

1. Clone / open the project

cd jenkins-mcp

2. Create a virtual environment

python -m venv .venv
.venv\Scripts\Activate.ps1

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

Copy the example file and fill in your real values - .env is git-ignored and never committed:

Copy-Item .env.example .env

Edit .env:

JENKINS_URL=http://localhost:8090
JENKINS_USER=admin
JENKINS_TOKEN=xxxxxxxx
MCP_TRANSPORT=stdio

server.py (via config.py) calls load_dotenv() on startup and reads every setting with os.getenv(), so the token is picked up automatically from .env - you don't need to (and shouldn't) pass JENKINS_TOKEN through mcp.json, claude_desktop_config.json, or any other client configuration file.

Run the Server

Stdio transport (default - used by Claude Desktop, VS Code, Cursor):

python server.py

Network transport (used for the Docker deployment or remote clients):

$env:MCP_TRANSPORT="streamable-http"; python server.py

Testing

Quick connectivity check once the server is configured:

python -c "from jenkins_client import JenkinsClient; import json; print(json.dumps(JenkinsClient().ping(), indent=2))"

You can also use the MCP Inspector to interactively call every tool:

npx @modelcontextprotocol/inspector python server.py

Then call the ping_jenkins tool first to validate connectivity/authentication before exercising job/build tools.

Claude Desktop Configuration

Edit claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config) and merge in:

{
  "mcpServers": {
    "jenkins-mcp": {
      "command": "C:\\path\\to\\jenkins-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\jenkins-mcp\\server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Security note: JENKINS_URL, JENKINS_USER and JENKINS_TOKEN are intentionally not set here. server.py loads them from the .env file in the project directory at startup (via python-dotenv), so the token never needs to appear in claude_desktop_config.json, mcp.json, or any other client configuration file that might get committed to source control.

VS Code MCP Configuration

Create .vscode/mcp.json in your workspace (or use the provided mcp.json as a template):

{
  "servers": {
    "jenkins-mcp": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": ["${workspaceFolder}/server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

JENKINS_URL, JENKINS_USER and JENKINS_TOKEN are deliberately omitted from mcp.json - they are loaded from your local .env file when server.py starts, so no credentials ever need to be written to this file (which is safe to commit).

Then run MCP: List Servers from the VS Code command palette and start jenkins-mcp.

Cursor MCP Configuration

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

As long as a .env file exists in cwd, server.py picks up JENKINS_URL / JENKINS_USER / JENKINS_TOKEN automatically - there's no need (and no reason) to duplicate them here.

Docker Deployment

Build and run with docker-compose (recommended - it also sets up host.docker.internal so the container can reach Jenkins running on your Docker Desktop host):

docker compose up --build -d

The server listens on http://localhost:8000 using the streamable-http transport. Point your MCP client at that URL, or override JENKINS_URL in a local .env file (docker-compose reads it automatically) if Jenkins is reachable via a different hostname/network.

Build the image manually:

docker build -t jenkins-mcp:latest .
docker run --rm -p 8000:8000 --env-file .env --add-host host.docker.internal:host-gateway jenkins-mcp:latest

Configuration Reference (.env)

Variable	Default	Description
JENKINS_URL	http://localhost:8090	Base Jenkins URL
JENKINS_USER	(empty)	Jenkins username
JENKINS_TOKEN	(empty)	Jenkins API token
JENKINS_VERIFY_SSL	true	Verify TLS certs for https:// Jenkins
JENKINS_TIMEOUT	30	Request timeout (seconds)
JENKINS_MAX_RETRIES	3	HTTP retry attempts
JENKINS_BACKOFF_FACTOR	0.5	Retry backoff factor
JENKINS_POOL_CONNECTIONS / JENKINS_POOL_MAXSIZE	10 / 20	Connection pool sizing
LOG_LEVEL	INFO	Logging level
LOG_FILE	logs/jenkins_mcp.log	Rotating log file path
DEFAULT_PAGE_SIZE	50	Default page size for paginated tools
JENKINS_CLI_JAR	(empty)	Optional path to jenkins-cli.jar
TERRAFORM_STATE_BUCKET / GCP_PROJECT	(empty)	Optional fallback hints for Terraform/GCP tools
MCP_TRANSPORT	stdio	stdio | streamable-http | sse

Security

• Never commit secrets. JENKINS_TOKEN (and JENKINS_USER) live only in your local .env file. .gitignore excludes .env and *.env, and mcp.json in this repo intentionally has no credential fields.
• Use .env.example as the template. It only contains placeholder values and is safe to commit; copy it to .env and fill in real values locally (or inject real env vars via your secrets manager / CI in production).
• Rotate tokens, don't reuse passwords. Generate a dedicated Jenkins API token (Jenkins → your user → Configure → API Token) instead of using your account password.
• Nothing sensitive is logged. jenkins_client.py only logs the Jenkins URL and username (never the token), and error messages (e.g. on HTTP 401) reference the names of the misconfigured variables, not their values, so credentials never end up in logs/jenkins_mcp.log or in tool error responses.
• Credential tools return metadata only. list_credentials_ids / get_credential_information never surface secret values, matching Jenkins' own credential API behavior.
• If a token does leak (e.g. committed by mistake), revoke/regenerate it immediately in Jenkins and scrub it from git history.

Tool Reference

All tools return {"status": "success", "data": {...}, "message": "..."} on success or {"status": "error", "message": "..."} on failure.

General

• ping_jenkins - version, URL, authentication status

Jobs

• list_jobs, get_job, create_pipeline_job, delete_job, enable_job, disable_job, copy_job, search_job

Builds

• trigger_build, trigger_build_with_parameters, stop_build, last_build_status, build_console_output, build_duration, build_artifacts, build_changes, queue_status, search_build

Pipeline

• get_pipeline_stages, get_stage_logs, replay_pipeline, blue_ocean_info, pipeline_health_report

Nodes

• list_nodes, node_status, node_executors, online_nodes, offline_nodes

Plugins

• installed_plugins, plugin_version, plugin_updates_available

System

• jenkins_version, installed_tools, system_information, quiet_down_mode, cancel_quiet_down, run_jenkins_cli_command (optional)

Credentials

• list_credentials_ids, get_credential_information (secret values are never returned)

Users

• current_user, who_am_i

Queue

• queue_information, cancel_queue_item

Views

• list_views, view_jobs

Terraform Support

• validate_terraform_pipeline, validate_jenkinsfile, detect_terraform_version, detect_workspace, show_tfvars, show_backend_configuration, show_terraform_plan_log, show_apply_log, show_destroy_log, detect_terraform_errors (classified into Authentication, Provider, Backend, Syntax, State Lock, Permission, Quota, Networking), terraform_plan_summary, workspace_cleanup

GCP Support

• detect_gcloud_version, current_gcp_project, service_account, enabled_apis, terraform_state_bucket, gcp_resource_inspector

Terraform/GCP tools work by parsing Jenkins console logs and workspace files (Jenkins has no native Terraform/GCP awareness), so they are most accurate immediately after a build has run.

Security Notes

• Credential tools never return secret values (passwords, private keys, secret text/bytes are stripped from responses).
• CSRF crumbs are obtained automatically and refreshed transparently on rejection.
• Configure JENKINS_VERIFY_SSL=true in production and use a scoped Jenkins API token rather than a personal password.