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. - 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 pi
Add this skill
npx mdskills install avisangle/jenkins-mcp-serverComprehensive Jenkins MCP server with 21 tools, multi-tier caching, and enterprise features
1# Jenkins MCP Server23[](https://opensource.org/licenses/Apache-2.0)4[](https://www.python.org/downloads/)5[](https://nodejs.org/)67An 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.89## Features1011### Core Capabilities12- **Job Management**: Trigger, list, search, and monitor Jenkins jobs with folder support13- **Build Status**: Real-time build status tracking and console log streaming14- **Pipeline Support**: Stage-by-stage pipeline execution monitoring with detailed logs15- **Artifact Management**: List, download, and search build artifacts across builds16- **Batch Operations**: Parallel job execution with priority queuing17- **Advanced Filtering**: Filter jobs by status, results, dates, and more with regex support1819### Performance & Reliability20- **Multi-Tier Caching System**: 5-tier intelligent caching (static, semi-static, dynamic, short-lived, permanent)21- **Retry Logic**: Built-in exponential backoff for improved reliability22- **CSRF Protection**: Automatic crumb token handling23- **Input Validation**: Robust Pydantic-based validation2425### Enterprise Features26- **Nested Job Support**: Full support for Jenkins folder structures27- **2FA Compatible**: Works with Jenkins two-factor authentication28- **Queue Management**: Real-time build queue monitoring29- **Transport Flexibility**: Supports STDIO and Streamable HTTP transports3031## Prerequisites3233- **Node.js**: 14.0.0 or higher34- **Python**: 3.12 or higher35- **Jenkins**: 2.401+ (recommended)36- **Jenkins API Token**: Required for authentication3738## Installation3940### Clone and Install4142```bash43# Clone this repository44git clone https://github.com/avisangle/jenkins-mcp-server45cd jenkins-mcp-server4647# Install Node.js dependencies48npm install4950# Install Python dependencies51pip install -e .52# Or using uv (recommended)53uv pip install -e .5455# Verify installation56node bin/jenkins-mcp.js --help57```5859### Dependencies6061**Python packages** (automatically installed):62- `mcp[cli]>=1.11.0` - Model Context Protocol63- `requests>=2.32.4` - HTTP library64- `cachetools>=5.5.0` - Caching utilities65- `python-dotenv` - Environment variable management66- `pydantic` - Data validation67- `fastapi` - HTTP transport support6869## Configuration7071### Environment Variables7273Create a `.env` file in your working directory:7475```bash76# Required Jenkins Configuration77JENKINS_URL="http://your-jenkins-server:8080"78JENKINS_USER="your-username"79JENKINS_API_TOKEN="your-api-token"8081# Optional: Retry Configuration82JENKINS_MAX_RETRIES=383JENKINS_RETRY_BASE_DELAY=1.084JENKINS_RETRY_MAX_DELAY=60.085JENKINS_RETRY_BACKOFF_MULTIPLIER=2.08687# Optional: Cache Configuration88JENKINS_CACHE_STATIC_TTL=3600 # 1 hour for static data89JENKINS_CACHE_SEMI_STATIC_TTL=300 # 5 minutes for semi-static90JENKINS_CACHE_DYNAMIC_TTL=30 # 30 seconds for dynamic data91JENKINS_CACHE_SHORT_TTL=10 # 10 seconds for short-lived9293# Optional: Cache Size Limits94JENKINS_CACHE_STATIC_SIZE=100095JENKINS_CACHE_SEMI_STATIC_SIZE=50096JENKINS_CACHE_DYNAMIC_SIZE=20097JENKINS_CACHE_PERMANENT_SIZE=200098JENKINS_CACHE_SHORT_SIZE=10099100# Optional: Content Limits101JENKINS_MAX_LOG_SIZE=1000102JENKINS_MAX_CONTENT_SIZE=10000103JENKINS_MAX_ARTIFACT_SIZE_MB=50104105# Optional: Server Configuration106MCP_PORT=8010107MCP_HOST=0.0.0.0108```109110### Getting a Jenkins API Token1111121. Log into your Jenkins server1132. Click on your username → **Configure**1143. Under **API Token** section, click **Add new Token**1154. Give it a name and click **Generate**1165. Copy the generated token (you won't be able to see it again)117118## Usage119120### Claude Desktop Integration121122Add to your `claude_desktop_config.json`:123124```json125{126 "mcpServers": {127 "jenkins": {128 "command": "node",129 "args": [130 "/path/to/jenkins-mcp-server/bin/jenkins-mcp.js"131 ],132 "env": {133 "JENKINS_URL": "http://your-jenkins-server:8080",134 "JENKINS_USER": "your-username",135 "JENKINS_API_TOKEN": "your-api-token"136 }137 }138 }139}140```141142### Command Line143144```bash145# STDIO mode (for Claude Desktop/MCP clients)146node bin/jenkins-mcp.js147148# HTTP mode (for MCP Gateway)149node bin/jenkins-mcp.js --transport streamable-http --port 8010150151# With custom host152node bin/jenkins-mcp.js --transport streamable-http --port 8080 --host localhost153```154155### Transport Modes156157**STDIO Mode** (default):158- Standard input/output communication159- Best for Claude Desktop integration160- No network ports required161162**Streamable HTTP Mode**:163- HTTP-based communication164- Useful for MCP Gateway or remote connections165- Requires port configuration166167## Available Tools168169The server exposes 21 MCP tools for Jenkins interaction:170171### Job Management172173#### `trigger_job`174Trigger a Jenkins job with optional parameters.175176**Parameters:**177- `job_name` (string): Job name or path (e.g., `"my-job"` or `"folder/my-job"`)178- `params` (object, optional): Job parameters as key-value pairs179180**Example:**181```json182{183 "job_name": "build-project",184 "params": {185 "BRANCH": "main",186 "VERSION": "1.0.0"187 }188}189```190191#### `get_job_info`192Get detailed information about a Jenkins job.193194**Parameters:**195- `job_name` (string): Job name or path196- `auto_search` (boolean, default: true): Perform pattern search if direct lookup fails197198**Returns:** Job configuration, parameters, last build info, and health status199200#### `list_jobs`201List Jenkins jobs with advanced filtering.202203**Parameters:**204- `recursive` (boolean, default: true): Include jobs in subfolders205- `max_depth` (integer, default: 10): Maximum folder depth206- `include_folders` (boolean, default: false): Include folder items207- `status_filter` (string, optional): Filter by color (e.g., `"blue"`, `"red"`)208- `last_build_result` (string, optional): Filter by result (`"SUCCESS"`, `"FAILURE"`, `"UNSTABLE"`)209- `days_since_last_build` (integer, optional): Filter by days since last build210- `enabled_only` (boolean, optional): Show only enabled jobs211212**Returns:** Hierarchical list of jobs with statistics213214#### `search_jobs`215Search for Jenkins jobs by pattern.216217**Parameters:**218- `pattern` (string): Search pattern (supports wildcards)219- `job_type` (string, default: `"job"`): Type filter (`"job"`, `"folder"`, `"pipeline"`)220- `use_regex` (boolean, default: false): Use regex pattern matching221- `max_depth` (integer, default: 10): Maximum search depth222223**Returns:** List of matching jobs with details224225#### `search_and_trigger`226Search for jobs and trigger all matches.227228**Parameters:**229- `pattern` (string): Search pattern230- `params` (object, optional): Parameters for all jobs231- `max_depth` (integer, default: 10): Maximum search depth232233**Returns:** Trigger status for each matched job234235#### `get_folder_info`236Get information about a Jenkins folder.237238**Parameters:**239- `folder_path` (string): Folder path (e.g., `"team/project"`)240241**Returns:** Folder details and contained jobs242243### Build Status & Monitoring244245#### `get_build_status`246Get status of a specific build.247248**Parameters:**249- `job_name` (string): Job name or path250- `build_number` (integer): Build number251252**Returns:** Build status, result, duration, timestamp, and executor info253254#### `get_console_log`255Get console output from a build.256257**Parameters:**258- `job_name` (string): Job name or path259- `build_number` (integer): Build number260- `start` (integer, default: 0): Starting byte offset261262**Returns:** Console log content and metadata263264#### `summarize_build_log`265Get a summarized version of build console log.266267**Parameters:**268- `job_name` (string): Job name or path269- `build_number` (integer): Build number270271**Returns:** Summarized log content272273### Pipeline Support274275#### `get_pipeline_status`276Get detailed pipeline execution status with stage information.277278**Parameters:**279- `job_name` (string): Pipeline job name280- `build_number` (integer): Build number281282**Returns:** Pipeline stages with status, duration, and logs for each stage283284### Artifact Management285286#### `list_build_artifacts`287List all artifacts from a build.288289**Parameters:**290- `job_name` (string): Job name or path291- `build_number` (integer): Build number292293**Returns:** List of artifacts with paths, sizes, and download URLs294295#### `download_build_artifact`296Download a specific build artifact.297298**Parameters:**299- `job_name` (string): Job name or path300- `build_number` (integer): Build number301- `artifact_path` (string): Relative path to artifact302- `max_size_mb` (integer, default: 50): Maximum download size in MB303304**Returns:** Artifact content (base64 encoded for binary) or text content305306#### `search_build_artifacts`307Search for artifacts across multiple builds.308309**Parameters:**310- `job_name` (string): Job name or path311- `pattern` (string): Search pattern for artifact names312- `max_builds` (integer, default: 10): Maximum builds to search313- `use_regex` (boolean, default: false): Use regex matching314315**Returns:** List of matching artifacts across builds316317### Batch Operations318319#### `batch_trigger_jobs`320Trigger multiple jobs in parallel with priority queuing.321322**Parameters:**323- `operations` (array): List of job operations324 - `job_name` (string): Job name325 - `params` (object, optional): Job parameters326 - `priority` (integer, default: 0): Execution priority (higher = earlier)327- `max_concurrent` (integer, default: 5): Maximum parallel executions328- `operation_name` (string, optional): Name for this batch operation329330**Returns:** Operation ID for monitoring331332**Example:**333```json334{335 "operations": [336 {"job_name": "build-frontend", "priority": 10},337 {"job_name": "build-backend", "priority": 10},338 {"job_name": "integration-tests", "priority": 5}339 ],340 "max_concurrent": 2341}342```343344#### `batch_monitor_jobs`345Monitor the status of a batch operation.346347**Parameters:**348- `operation_id` (string): Operation ID from batch_trigger_jobs349350**Returns:** Status of each job in the batch operation351352#### `batch_cancel_jobs`353Cancel a batch operation.354355**Parameters:**356- `operation_id` (string): Operation ID to cancel357- `cancel_running_builds` (boolean, default: false): Also cancel running builds358359**Returns:** Cancellation status360361### Queue & Server Management362363#### `get_queue_info`364Get information about the Jenkins build queue.365366**Returns:** List of queued items with job names, wait times, and reasons367368#### `server_info`369Get basic Jenkins server information.370371**Returns:** Version, root URL, and system information372373### Cache Management374375#### `get_cache_statistics`376Get statistics about the caching system.377378**Returns:** Cache hit/miss rates, sizes, and memory usage379380#### `clear_cache`381Clear cached data.382383**Parameters:**384- `cache_type` (string, optional): Specific cache to clear (`"static"`, `"dynamic"`, etc.)385- `job_name` (string, optional): Clear cache for specific job386387**Returns:** Cache clear status388389#### `warm_cache`390Pre-populate cache with commonly used data.391392**Parameters:**393- `operations` (array, optional): List of operations to warm (`["list_jobs"`, `"server_info"]`)394395**Returns:** Warm-up status and timing396397## Caching System398399The server implements a sophisticated 5-tier caching system for optimal performance:400401### Cache Tiers402403| Tier | TTL | Use Case | Example Data |404|------|-----|----------|--------------|405| **Static** | 1 hour | Rarely changing data | Job definitions, server info |406| **Semi-Static** | 5 minutes | Occasionally changing | Job lists, folder structures |407| **Dynamic** | 30 seconds | Frequently changing | Build statuses, queue info |408| **Short-Lived** | 10 seconds | Real-time data | Active build logs |409| **Permanent** | No expiry | Immutable data | Completed build artifacts |410411### Cache Invalidation412413Caches are automatically invalidated when:414- Jobs are triggered415- Build states change416- Manual cache clear operations417418### Cache Configuration419420Customize cache behavior via environment variables (see Configuration section).421422## Error Handling423424The server provides detailed error messages with suggestions:425426- **404 Not Found**: Includes search suggestions for similar job names427- **401 Unauthorized**: Prompts to check credentials428- **403 Forbidden**: Explains permission issues429- **Connection Errors**: Automatic retry with exponential backoff430431## Nested Job Support432433Fully supports Jenkins folder structures:434435```json436{437 "job_name": "team-alpha/backend/build-service"438}439```440441All tools accept nested paths with automatic path handling.442443## Performance Optimization444445### Built-in Optimizations446- Multi-tier intelligent caching447- Concurrent batch operations with throttling448- Request deduplication449- Lazy loading of large datasets450- Configurable content size limits451452### Best Practices4531. Use batch operations for multiple jobs4542. Enable caching for repeated operations4553. Set appropriate `max_depth` when searching4564. Use `status_filter` to reduce data transfer4575. Warm cache before high-traffic periods458459## Security460461### Authentication462- Jenkins API token authentication463- Support for Jenkins 2FA environments464- Automatic CSRF crumb token handling465466### Security Features467- No password storage (API tokens only)468- TLS/SSL support for Jenkins HTTPS endpoints469- Input validation on all parameters470- Configurable artifact download size limits471472## Troubleshooting473474### Common Issues475476**Python version error:**477```bash478# Check Python version479python3 --version # Must be 3.12+480```481482**Missing dependencies:**483```bash484# Reinstall Python packages485pip install -e .486# Or487uv pip install -e .488```489490**Connection refused:**491- Verify `JENKINS_URL` is correct and accessible492- Check Jenkins server is running493- Verify network connectivity494495**Authentication failed:**496- Regenerate Jenkins API token497- Check `JENKINS_USER` matches your Jenkins username498- Verify token has necessary permissions499500**Job not found:**501- Check job name spelling and case502- Use `search_jobs` to find correct job name503- Verify you have permissions to access the job504505### Debug Logging506507The server logs to stderr with request IDs for troubleshooting:508509```5102025-11-12 10:30:45 - jenkins_mcp - INFO - [req-abc123] Received request to trigger job: 'build-project'511```512513## Development514515### Running Tests516517```bash518# Install test dependencies519pip install -e ".[test]"520521# Run tests522pytest523```524525### Project Structure526527```528jenkins-mcp-server/529├── bin/530│ └── jenkins-mcp.js # Node.js CLI entry point531├── python/532│ └── jenkins_mcp_server_enhanced.py # Main MCP server implementation533├── scripts/534│ └── check-python.js # Python environment checker535├── .env.example # Example environment configuration536├── pyproject.toml # Python package configuration537├── package.json # Node.js package configuration538└── README.md # This file539```540541## Contributing542543Contributions, bug reports, and feature requests are welcome.544545## License546547Apache License 2.0 - See [LICENSE](LICENSE) file for details.548549## Related Projects550551- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)552- **Claude Desktop**: [Anthropic Claude](https://www.anthropic.com/claude)553554## Support555556For issues and questions:557- Open an issue on [GitHub Issues](https://github.com/avisangle/jenkins-mcp-server/issues)558- Check existing issues for solutions559- Provide Jenkins version, MCP server version, and error logs when reporting issues560561---562563**Version**: 1.0.7564**Last Updated**: 2025-11-13565
Full transparency — inspect the skill content before installing.