avisangle/jenkins-mcp-server

License Python Node.js

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

# 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:

# 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

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

Usage

Claude Desktop Integration

Add to your claude_desktop_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

# 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:

{
  "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:

{
  "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:

{
  "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

1. Use batch operations for multiple jobs
2. Enable caching for repeated operations
3. Set appropriate max_depth when searching
4. Use status_filter to reduce data transfer
5. 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:

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

Missing dependencies:

# 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:

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

Development

Running Tests

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

# Run tests
pytest

Project Structure

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