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.
README Documentation
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)
# 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
- Log into your Jenkins instance
- Click your username → Configure
- Scroll to API Token section
- Click Add new Token
- Give it a name and click Generate
- 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
Mode | Use Case | Command |
---|---|---|
STDIO | Claude Desktop, direct MCP clients | jenkins-mcp |
HTTP | MCP Gateway, web integrations | jenkins-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 daysenabled_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 daysenabled_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 jobparams
(object, optional): Job parameterspriority
(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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Commit changes:
git commit -m 'Add amazing feature'
- Push to branch:
git push origin feature/amazing-feature
- 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