README.md•16.5 kB
# Jenkins MCP Server
[](https://badge.fury.io/js/@ashwinighuge%2Fjenkins-mcp-server)
[](https://opensource.org/licenses/Apache-2.0)
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)
```bash
# 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`:
```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)
```bash
# Install globally for system-wide access
npm install -g @ashwinighuge/jenkins-mcp-server
# Verify installation
jenkins-mcp --help
```
### Method 2: Development Setup
```bash
# 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:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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**
```bash
# 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)**
```bash
# 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
```bash
# 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](LICENSE) file for details.
## 🙋♂️ Support
- **Documentation**: [GitHub README](https://github.com/AshwiniGhuge3012/jenkins-mcp-server#readme)
- **Issues**: [GitHub Issues](https://github.com/AshwiniGhuge3012/jenkins-mcp-server/issues)
- **npm Package**: [@ashwinighuge/jenkins-mcp-server](https://www.npmjs.com/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
---