JUHE API Marketplace
AshwiniGhuge3012 avatar
MCP Server

Jenkins MCP Server

An MCP server for interacting with a Jenkins CI/CD server. Allows you to trigger jobs, check build statuses, and manage your Jenkins instance through MCP.

4
GitHub Stars
8/23/2025
Last Updated
MCP Server Configuration
1{
2 "name": "jenkins",
3 "command": "jenkins-mcp",
4 "env": {
5 "JENKINS_URL": "http://your-jenkins-server: 8080",
6 "JENKINS_USER": "your-username",
7 "JENKINS_API_TOKEN": "your-api-token"
8 }
9}
JSON9 lines

README Documentation

Jenkins MCP Server

npm version

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)

# Global installation
npm install -g @ashwinighuge/jenkins-mcp-server

# Or use directly with npx
npx @ashwinighuge/jenkins-mcp-server --help

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "jenkins-mcp",
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_API_TOKEN": "your-api-token"
      }
    }
  }
}

✨ 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)

# Install globally for system-wide access
npm install -g @ashwinighuge/jenkins-mcp-server

# Verify installation
jenkins-mcp --help

Method 2: Development Setup

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

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -r requirements.txt  # or use uv pip install

# Run locally
node bin/jenkins-mcp.js --help

🔐 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: Server Configuration
MCP_PORT=8010
MCP_HOST=0.0.0.0

# 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: Performance Cache Configuration
JENKINS_CACHE_STATIC_TTL=3600        # 1 hour
JENKINS_CACHE_SEMI_STATIC_TTL=300    # 5 minutes
JENKINS_CACHE_DYNAMIC_TTL=30         # 30 seconds
JENKINS_CACHE_SHORT_TTL=10           # 10 seconds
JENKINS_CACHE_STATIC_SIZE=1000       # Max cached items
JENKINS_CACHE_SEMI_STATIC_SIZE=500
JENKINS_CACHE_DYNAMIC_SIZE=200
JENKINS_CACHE_PERMANENT_SIZE=2000
JENKINS_CACHE_SHORT_SIZE=100

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

# STDIO mode (default, for Claude Desktop)
jenkins-mcp

# HTTP mode (for MCP Gateway)
jenkins-mcp --transport streamable-http --port 8010

# Custom host and port
jenkins-mcp --transport streamable-http --host localhost --port 9000

# Show help
jenkins-mcp --help

Transport Modes

ModeUse CaseCommand
STDIOClaude Desktop, direct MCP clientsjenkins-mcp
HTTPMCP Gateway, web integrationsjenkins-mcp --transport streamable-http

Advanced Usage Examples

# Using with npx (no global installation)
npx @ashwinighuge/jenkins-mcp-server

# Using environment variables
JENKINS_URL=http://localhost:8080 JENKINS_USER=admin JENKINS_API_TOKEN=abc123 jenkins-mcp

# HTTP mode with custom configuration
jenkins-mcp --transport streamable-http --host 0.0.0.0 --port 8080

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

# Start server in HTTP mode
jenkins-mcp --transport streamable-http --port 8010

# Example API calls (using curl)
curl -X POST http://localhost:8010/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {"name": "list_jobs", "arguments": {}}}'

Batch Operations Example

# Trigger multiple jobs with different priorities
jenkins-mcp # Then use batch_trigger_jobs tool with:
{
  "operations": [
    {"job_name": "unit-tests", "priority": 1},
    {"job_name": "integration-tests", "priority": 2},
    {"job_name": "deploy-staging", "priority": 3}
  ],
  "max_concurrent": 3,
  "wait_for_completion": true
}

🔧 Troubleshooting

Common Issues

Python Dependencies

# If Python packages fail to install automatically
pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

# Or using uv (recommended)
uv pip install mcp[cli] pydantic requests python-dotenv fastapi cachetools

Permission Issues (Linux/macOS)

# If permission denied
sudo npm install -g @ashwinighuge/jenkins-mcp-server

# Or use user-level installation
npm install -g @ashwinighuge/jenkins-mcp-server --prefix ~/.local

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

# Enable verbose logging
DEBUG=jenkins-mcp jenkins-mcp

# Check Python dependencies
jenkins-mcp --help  # Will validate dependencies

📊 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

🏗️ 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

Quick Install

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source