Jenkins MCP Server

An enterprise-grade MCP (Model Context Protocol) server for seamless Jenkins CI/CD integration. Enables AI assistants like Claude to interact with Jenkins through a comprehensive, production-ready API.

🚀 Quick Start

npm Installation (Recommended)

Claude Desktop Integration

Add to your claude_desktop_config.json:

Related MCP server: Project Content Server

✨ Features

• 🔧 Job Management: Trigger, list, search, and monitor Jenkins jobs with full 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 multiple builds

• ⚡ Batch Operations: Parallel job execution with intelligent priority queuing

• 🚀 Performance Caching: Multi-tier intelligent caching system with automatic invalidation

• 🔍 Advanced Filtering: Filter jobs by status, results, dates, and more with regex support

• 📋 Queue Management: Real-time build queue monitoring and management

• 🔒 Enterprise Security: CSRF protection, 2FA support, and secure authentication

• 🌐 Cross-Platform: Works on Windows, macOS, and Linux

• 🔄 Retry Logic: Built-in exponential backoff for improved reliability

• 📡 Transport Flexibility: Supports both STDIO and HTTP transports

• ✅ Input Validation: Robust Pydantic-based validation and error handling

📋 Prerequisites

• Node.js: 14.0.0 or higher

• Python: 3.12 or higher

• Jenkins: 2.401+ (recommended)

• Jenkins API Token: For authentication

🛠 Installation Methods

Method 1: npm (Recommended)

Method 2: Development Setup

🔐 Configuration

Environment Variables

Create a .env file in your working directory:

Getting Jenkins API Token

1. Log into your Jenkins instance

2. Click your username → Configure

3. Scroll to API Token section

4. Click Add new Token

5. Give it a name and click Generate

6. Copy the generated token (save it securely!)

🚀 Usage

Command Line Interface

Transport Modes

Advanced Usage Examples

Available Tools

Here is a list of the tools exposed by this MCP server:

trigger_job

• Description: Triggers a Jenkins job with optional parameters.

• Parameters:

  • job_name (string): The name of the Jenkins job.

  • params (object, optional): Job parameters as a JSON object. For multiselect parameters, pass an array of strings.

• Returns: A confirmation message with the queue URL.

get_job_info

• Description: Gets detailed information about a Jenkins job, including its parameters.

• Parameters:

  • job_name (string): The name of the Jenkins job.

• Returns: An object containing the job's description, parameters, and last build number.

get_build_status

• Description: Gets the status of a specific build.

• Parameters:

  • job_name (string): The name of the Jenkins job.

  • build_number (integer): The build number.

• Returns: An object with the build status, timestamp, duration, and URL.

get_console_log

• Description: Retrieves the console log for a specific build.

• Parameters:

  • job_name (string): The name of the Jenkins job.

  • build_number (integer): The build number.

  • start (integer, optional): The starting byte position for fetching the log.

• Returns: The console log text and information about whether more data is available.

list_jobs

• Description: Lists all available jobs on the Jenkins server with advanced filtering capabilities.

• Parameters:

  • recursive (boolean, optional): If True, recursively traverse folders (default: True)

  • max_depth (integer, optional): Maximum depth to recurse (default: 10)

  • include_folders (boolean, optional): Whether to include folder items (default: False)

  • status_filter (string, optional): Filter by job status: "building", "queued", "idle", "disabled"

  • last_build_result (string, optional): Filter by last build result: "SUCCESS", "FAILURE", "UNSTABLE", "ABORTED", "NOT_BUILT"

  • days_since_last_build (integer, optional): Only jobs built within the last N days

  • enabled_only (boolean, optional): If True, only enabled jobs; if False, only disabled jobs

• Returns: A list of jobs with enhanced metadata including build status and timestamps.

search_jobs

• Description: Search for Jenkins jobs using pattern matching with advanced filtering.

• Parameters:

  • pattern (string): Pattern to match job names (supports wildcards like 'build*', 'test', etc.)

  • job_type (string, optional): Filter by type - "job", "folder", or "all" (default: "job")

  • max_depth (integer, optional): Maximum depth to search (default: 10)

  • use_regex (boolean, optional): If True, treat pattern as regex instead of wildcard (default: False)

  • status_filter (string, optional): Filter by job status: "building", "queued", "idle", "disabled"

  • last_build_result (string, optional): Filter by last build result: "SUCCESS", "FAILURE", "UNSTABLE", "ABORTED", "NOT_BUILT"

  • days_since_last_build (integer, optional): Only jobs built within the last N days

  • enabled_only (boolean, optional): If True, only enabled jobs; if False, only disabled jobs

• Returns: A list of matching jobs with enhanced metadata and full paths.

get_queue_info

• Description: Gets information about builds currently in the queue.

• Parameters: None

• Returns: A list of items in the queue.

server_info

• Description: Gets basic information about the Jenkins server.

• Parameters: None

• Returns: The Jenkins version and URL.

get_pipeline_status

• Description: Gets detailed pipeline stage status for Jenkins Pipeline job builds.

• Parameters:

  • job_name (string): The name of the Jenkins Pipeline job.

  • build_number (integer): The build number.

• Returns: Pipeline execution details including stage-by-stage status, timing, duration, and logs.

list_build_artifacts

• Description: List all artifacts for a specific Jenkins build.

• Parameters:

  • job_name (string): Name of the Jenkins job.

  • build_number (integer): Build number to list artifacts for.

• Returns: Information about all artifacts including filenames, sizes, and download URLs.

download_build_artifact

• Description: Download a specific build artifact content (text-based artifacts only for safety).

• Parameters:

  • job_name (string): Name of the Jenkins job.

  • build_number (integer): Build number containing the artifact.

  • artifact_path (string): Relative path to the artifact (from list_build_artifacts).

  • max_size_mb (integer, optional): Maximum file size to download in MB (default: 50MB).

• Returns: Artifact content (for text files) or download information.

search_build_artifacts

• Description: Search for artifacts across recent builds of a job using pattern matching.

• Parameters:

  • job_name (string): Name of the Jenkins job to search.

  • pattern (string): Pattern to match artifact names (wildcards or regex).

  • max_builds (integer, optional): Maximum number of recent builds to search (default: 10).

  • use_regex (boolean, optional): If True, treat pattern as regex instead of wildcard (default: False).

• Returns: List of matching artifacts across builds with their metadata.

batch_trigger_jobs

• Description: Trigger multiple Jenkins jobs in batch with parallel execution and priority queuing.

• Parameters:

  • operations (array): List of job operations, each containing:

    • job_name (string): Name of the Jenkins job

    • params (object, optional): Job parameters

    • priority (integer, optional): Priority 1-10 (1=highest, default: 1)

  • max_concurrent (integer, optional): Maximum concurrent job triggers (default: 5)

  • fail_fast (boolean, optional): Stop processing on first failure (default: false)

  • wait_for_completion (boolean, optional): Wait for all jobs to complete (default: false)

• Returns: Batch operation response with operation ID, results, and execution statistics.

batch_monitor_jobs

• Description: Monitor the status of a batch operation and its individual jobs.

• Parameters:

  • operation_id (string): The operation ID returned from batch_trigger_jobs.

• Returns: Current status of the batch operation including progress and individual job statuses.

batch_cancel_jobs

• Description: Cancel a batch operation and optionally cancel running builds.

• Parameters:

  • operation_id (string): The operation ID to cancel.

  • cancel_running_builds (boolean, optional): Attempt to cancel running builds (default: false).

• Returns: Cancellation status and results.

get_cache_statistics

• Description: Get comprehensive cache performance metrics and utilization statistics.

• Parameters: None

• Returns: Cache hit rates, utilization percentages, and detailed statistics for all cache types.

clear_cache

• Description: Clear caches with fine-grained control for performance management.

• Parameters:

  • cache_type (string, optional): Type of cache to clear ('all', 'static', 'semi_static', 'dynamic', 'permanent', 'short')

  • job_name (string, optional): Clear caches for a specific job only

• Returns: Confirmation of cache clearing operation.

warm_cache

• Description: Pre-load frequently accessed data into caches for improved performance.

• Parameters:

  • operations (array, optional): Operations to warm ('server_info', 'job_list', 'queue_info')

• Returns: Results of cache warming operations with success/failure status.

summarize_build_log

• Description: (Demonstration) Summarizes a build log using a pre-configured LLM prompt.

• Parameters:

  • job_name (string): The name of the Jenkins job.

  • build_number (integer): The build number.

• Returns: A placeholder summary and the prompt that would be used.

💡 Usage Examples

With Claude Desktop

Once configured in claude_desktop_config.json, you can ask Claude:

"List all Jenkins jobs"

"Trigger the deploy-prod job with version parameter 1.2.3"

"Show me the console log for build #45 of the api-tests job"

"What's the status of all jobs that failed in the last 24 hours?"

With MCP Gateway

Batch Operations Example

🔧 Troubleshooting

Common Issues

Python Dependencies

Permission Issues (Linux/macOS)

Jenkins Connection Issues

• Verify JENKINS_URL is accessible

• Ensure API token is valid and not expired

• Check firewall/proxy settings

• For HTTPS, verify SSL certificates

2FA/CSRF Issues

• The server handles CSRF tokens automatically

• For 2FA environments, use API tokens (not passwords)

• Email OTP and similar 2FA methods are supported

Debug Mode

📊 Performance Features

• Multi-tier Caching: Intelligent caching with automatic invalidation

• Batch Processing: Parallel job execution with priority queuing

• Retry Logic: Exponential backoff for network reliability

• Connection Pooling: Efficient HTTP connection management

• Memory Optimization: Configurable cache sizes and TTL values

🤝 Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Commit changes: git commit -m 'Add amazing feature'

4. Push to branch: git push origin feature/amazing-feature

5. Open a Pull Request

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🙋‍♂️ Support

• Documentation: GitHub README

• Issues: GitHub Issues

• npm Package: @ashwinighuge/jenkins-mcp-server

🏗️ Architecture

Built with:

• Python 3.12+ - Core server implementation

• FastMCP - MCP protocol handling

• Node.js - Cross-platform wrapper and process management

• Pydantic - Data validation and serialization

• Requests - HTTP client with retry logic

• CacheTools - Multi-tier performance caching