Jenkins MCP Server

An enterprise-grade MCP (Model Context Protocol) server for Jenkins CI/CD integration with advanced features including multi-tier caching, pipeline monitoring, artifact management, and batch operations.

Features

Core Capabilities

Job Management: Trigger, list, search, and monitor Jenkins jobs with folder support
Build Status: Real-time build status tracking and console log streaming
Pipeline Support: Stage-by-stage pipeline execution monitoring with detailed logs
Artifact Management: List, download, and search build artifacts across builds
Batch Operations: Parallel job execution with priority queuing
Advanced Filtering: Filter jobs by status, results, dates, and more with regex support

Performance & Reliability

Multi-Tier Caching System: 5-tier intelligent caching (static, semi-static, dynamic, short-lived, permanent)
Retry Logic: Built-in exponential backoff for improved reliability
CSRF Protection: Automatic crumb token handling
Input Validation: Robust Pydantic-based validation

Enterprise Features

Nested Job Support: Full support for Jenkins folder structures
2FA Compatible: Works with Jenkins two-factor authentication
Queue Management: Real-time build queue monitoring
Transport Flexibility: Supports STDIO and Streamable HTTP transports

Prerequisites

Node.js: 14.0.0 or higher
Python: 3.12 or higher
Jenkins: 2.401+ (recommended)
Jenkins API Token: Required for authentication

Installation

Clone and Install

bash

# Clone this repository
git clone https://github.com/avisangle/jenkins-mcp-server
cd jenkins-mcp-server

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -e .
# Or using uv (recommended)
uv pip install -e .

# Verify installation
node bin/jenkins-mcp.js --help

Dependencies

Python packages (automatically installed):

mcp[cli]>=1.11.0 - Model Context Protocol
requests>=2.32.4 - HTTP library
cachetools>=5.5.0 - Caching utilities
python-dotenv - Environment variable management
pydantic - Data validation
fastapi - HTTP transport support

Configuration

Environment Variables

Create a .env file in your working directory:

bash

# Required Jenkins Configuration
JENKINS_URL="http://your-jenkins-server:8080"
JENKINS_USER="your-username"
JENKINS_API_TOKEN="your-api-token"

# Optional: Retry Configuration
JENKINS_MAX_RETRIES=3
JENKINS_RETRY_BASE_DELAY=1.0
JENKINS_RETRY_MAX_DELAY=60.0
JENKINS_RETRY_BACKOFF_MULTIPLIER=2.0

# Optional: Cache Configuration
JENKINS_CACHE_STATIC_TTL=3600        # 1 hour for static data
JENKINS_CACHE_SEMI_STATIC_TTL=300    # 5 minutes for semi-static
JENKINS_CACHE_DYNAMIC_TTL=30         # 30 seconds for dynamic data
JENKINS_CACHE_SHORT_TTL=10           # 10 seconds for short-lived

# Optional: Cache Size Limits
JENKINS_CACHE_STATIC_SIZE=1000
JENKINS_CACHE_SEMI_STATIC_SIZE=500
JENKINS_CACHE_DYNAMIC_SIZE=200
JENKINS_CACHE_PERMANENT_SIZE=2000
JENKINS_CACHE_SHORT_SIZE=100

# Optional: Content Limits
JENKINS_MAX_LOG_SIZE=1000
JENKINS_MAX_CONTENT_SIZE=10000
JENKINS_MAX_ARTIFACT_SIZE_MB=50

# Optional: Server Configuration
MCP_PORT=8010
MCP_HOST=0.0.0.0

Getting a Jenkins API Token

Log into your Jenkins server
Click on your username → Configure
Under API Token section, click Add new Token
Give it a name and click Generate
Copy the generated token (you won't be able to see it again)

Usage

Claude Desktop Integration

Add to your claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "jenkins": {
      "command": "node",
      "args": [
        "/path/to/jenkins-mcp-server/bin/jenkins-mcp.js"
      ],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

Command Line

bash

# STDIO mode (for Claude Desktop/MCP clients)
node bin/jenkins-mcp.js

# HTTP mode (for MCP Gateway)
node bin/jenkins-mcp.js --transport streamable-http --port 8010

# With custom host
node bin/jenkins-mcp.js --transport streamable-http --port 8080 --host localhost

Transport Modes

STDIO Mode (default):

Standard input/output communication
Best for Claude Desktop integration
No network ports required

Streamable HTTP Mode:

HTTP-based communication
Useful for MCP Gateway or remote connections
Requires port configuration

Available Tools

The server exposes 21 MCP tools for Jenkins interaction:

Job Management

`trigger_job`

Trigger a Jenkins job with optional parameters.

Parameters:

job_name (string): Job name or path (e.g., "my-job" or "folder/my-job")
params (object, optional): Job parameters as key-value pairs

Example:

config.json

{
  "job_name": "build-project",
  "params": {
    "BRANCH": "main",
    "VERSION": "1.0.0"
  }
}

`get_job_info`

Get detailed information about a Jenkins job.

Parameters:

job_name (string): Job name or path
auto_search (boolean, default: true): Perform pattern search if direct lookup fails

Returns: Job configuration, parameters, last build info, and health status

`list_jobs`

List Jenkins jobs with advanced filtering.

Parameters:

recursive (boolean, default: true): Include jobs in subfolders
max_depth (integer, default: 10): Maximum folder depth
include_folders (boolean, default: false): Include folder items
status_filter (string, optional): Filter by color (e.g., "blue", "red")
last_build_result (string, optional): Filter by result ("SUCCESS", "FAILURE", "UNSTABLE")
days_since_last_build (integer, optional): Filter by days since last build
enabled_only (boolean, optional): Show only enabled jobs

Returns: Hierarchical list of jobs with statistics

`search_jobs`

Search for Jenkins jobs by pattern.

Parameters:

pattern (string): Search pattern (supports wildcards)
job_type (string, default: "job"): Type filter ("job", "folder", "pipeline")
use_regex (boolean, default: false): Use regex pattern matching
max_depth (integer, default: 10): Maximum search depth

Returns: List of matching jobs with details

`search_and_trigger`

Search for jobs and trigger all matches.

Parameters:

pattern (string): Search pattern
params (object, optional): Parameters for all jobs
max_depth (integer, default: 10): Maximum search depth

Returns: Trigger status for each matched job

`get_folder_info`

Get information about a Jenkins folder.

Parameters:

folder_path (string): Folder path (e.g., "team/project")

Returns: Folder details and contained jobs

Build Status & Monitoring

`get_build_status`

Get status of a specific build.

Parameters:

job_name (string): Job name or path
build_number (integer): Build number

Returns: Build status, result, duration, timestamp, and executor info

`get_console_log`

Get console output from a build.

Parameters:

job_name (string): Job name or path
build_number (integer): Build number
start (integer, default: 0): Starting byte offset

Returns: Console log content and metadata

`summarize_build_log`

Get a summarized version of build console log.

Parameters:

job_name (string): Job name or path
build_number (integer): Build number

Returns: Summarized log content

Pipeline Support

`get_pipeline_status`

Get detailed pipeline execution status with stage information.

Parameters:

job_name (string): Pipeline job name
build_number (integer): Build number

Returns: Pipeline stages with status, duration, and logs for each stage

Artifact Management

`list_build_artifacts`

List all artifacts from a build.

Parameters:

job_name (string): Job name or path
build_number (integer): Build number

Returns: List of artifacts with paths, sizes, and download URLs

`download_build_artifact`

Download a specific build artifact.

Parameters:

job_name (string): Job name or path
build_number (integer): Build number
artifact_path (string): Relative path to artifact
max_size_mb (integer, default: 50): Maximum download size in MB

Returns: Artifact content (base64 encoded for binary) or text content

`search_build_artifacts`

Search for artifacts across multiple builds.

Parameters:

job_name (string): Job name or path
pattern (string): Search pattern for artifact names
max_builds (integer, default: 10): Maximum builds to search
use_regex (boolean, default: false): Use regex matching

Returns: List of matching artifacts across builds

Batch Operations

`batch_trigger_jobs`

Trigger multiple jobs in parallel with priority queuing.

Parameters:

operations (array): List of job operations
- job_name (string): Job name
- params (object, optional): Job parameters
- priority (integer, default: 0): Execution priority (higher = earlier)
max_concurrent (integer, default: 5): Maximum parallel executions
operation_name (string, optional): Name for this batch operation

Returns: Operation ID for monitoring

Example:

config.json

{
  "operations": [
    {"job_name": "build-frontend", "priority": 10},
    {"job_name": "build-backend", "priority": 10},
    {"job_name": "integration-tests", "priority": 5}
  ],
  "max_concurrent": 2
}

`batch_monitor_jobs`

Monitor the status of a batch operation.

Parameters:

operation_id (string): Operation ID from batch_trigger_jobs

Returns: Status of each job in the batch operation

`batch_cancel_jobs`

Cancel a batch operation.

Parameters:

operation_id (string): Operation ID to cancel
cancel_running_builds (boolean, default: false): Also cancel running builds

Returns: Cancellation status

Queue & Server Management

`get_queue_info`

Get information about the Jenkins build queue.

Returns: List of queued items with job names, wait times, and reasons

`server_info`

Get basic Jenkins server information.

Returns: Version, root URL, and system information

Cache Management

`get_cache_statistics`

Get statistics about the caching system.

Returns: Cache hit/miss rates, sizes, and memory usage

`clear_cache`

Clear cached data.

Parameters:

cache_type (string, optional): Specific cache to clear ("static", "dynamic", etc.)
job_name (string, optional): Clear cache for specific job

Returns: Cache clear status

`warm_cache`

Pre-populate cache with commonly used data.

Parameters:

operations (array, optional): List of operations to warm (["list_jobs", "server_info"])

Returns: Warm-up status and timing

Caching System

The server implements a sophisticated 5-tier caching system for optimal performance:

Cache Tiers

Tier	TTL	Use Case	Example Data
Static	1 hour	Rarely changing data	Job definitions, server info
Semi-Static	5 minutes	Occasionally changing	Job lists, folder structures
Dynamic	30 seconds	Frequently changing	Build statuses, queue info
Short-Lived	10 seconds	Real-time data	Active build logs
Permanent	No expiry	Immutable data	Completed build artifacts

Cache Invalidation

Caches are automatically invalidated when:

Jobs are triggered
Build states change
Manual cache clear operations

Cache Configuration

Customize cache behavior via environment variables (see Configuration section).

Error Handling

The server provides detailed error messages with suggestions:

404 Not Found: Includes search suggestions for similar job names
401 Unauthorized: Prompts to check credentials
403 Forbidden: Explains permission issues
Connection Errors: Automatic retry with exponential backoff

Nested Job Support

Fully supports Jenkins folder structures:

config.json

{
  "job_name": "team-alpha/backend/build-service"
}

All tools accept nested paths with automatic path handling.

Performance Optimization

Built-in Optimizations

Multi-tier intelligent caching
Concurrent batch operations with throttling
Request deduplication
Lazy loading of large datasets
Configurable content size limits

Best Practices

Use batch operations for multiple jobs
Enable caching for repeated operations
Set appropriate max_depth when searching
Use status_filter to reduce data transfer
Warm cache before high-traffic periods

Security

Authentication

Jenkins API token authentication
Support for Jenkins 2FA environments
Automatic CSRF crumb token handling

Security Features

No password storage (API tokens only)
TLS/SSL support for Jenkins HTTPS endpoints
Input validation on all parameters
Configurable artifact download size limits

Troubleshooting

Common Issues

Python version error:

bash

# Check Python version
python3 --version  # Must be 3.12+

Missing dependencies:

bash

# Reinstall Python packages
pip install -e .
# Or
uv pip install -e .

Connection refused:

Verify JENKINS_URL is correct and accessible
Check Jenkins server is running
Verify network connectivity

Authentication failed:

Regenerate Jenkins API token
Check JENKINS_USER matches your Jenkins username
Verify token has necessary permissions

Job not found:

Check job name spelling and case
Use search_jobs to find correct job name
Verify you have permissions to access the job

Debug Logging

The server logs to stderr with request IDs for troubleshooting:

Code

2025-11-12 10:30:45 - jenkins_mcp - INFO - [req-abc123] Received request to trigger job: 'build-project'

Development

Running Tests

bash

# Install test dependencies
pip install -e ".[test]"

# Run tests
pytest

Project Structure

Code

jenkins-mcp-server/
├── bin/
│   └── jenkins-mcp.js          # Node.js CLI entry point
├── python/
│   └── jenkins_mcp_server_enhanced.py  # Main MCP server implementation
├── scripts/
│   └── check-python.js         # Python environment checker
├── .env.example                # Example environment configuration
├── pyproject.toml              # Python package configuration
├── package.json                # Node.js package configuration
└── README.md                   # This file

Contributing

Contributions, bug reports, and feature requests are welcome.

License

Apache License 2.0 - See LICENSE file for details.

Related Projects

MCP Protocol: Model Context Protocol
Claude Desktop: Anthropic Claude

Support

For issues and questions:

Open an issue on GitHub Issues
Check existing issues for solutions
Provide Jenkins version, MCP server version, and error logs when reporting issues

Version: 1.0.7 Last Updated: 2025-11-13