Jenkins MCP Server is an MCP (Model Context Protocol) server used to interact with a Jenkins server, allowing users to trigger jobs, view build status, and manage Jenkins instances via MCP. It is positioned as an enterprise-grade server for Jenkins CI/CD integration.
Key Capabilities
- Job Management: Trigger, list, search, and monitor Jenkins jobs, with support for folder structures.
- Build Status: Real-time build status tracking and streaming retrieval of console logs.
- Pipeline Support: Monitor pipeline execution stage by stage, with detailed logs for each stage.
- Artifact Management: List, download, and search build artifacts across builds.
- Batch Operations: Execute multiple jobs in parallel via a priority queue.
- Advanced Filtering: Filter jobs by status, result, date, and other conditions, with regular expression support.
Performance and Reliability
- Multi-level Caching System: Five-level intelligent caching (static, semi-static, dynamic, short-term, permanent).
- Retry Logic: Built-in exponential backoff to improve reliability.
- CSRF Protection: Automatically handles crumb tokens.
- Input Validation: Robust validation based on Pydantic.
Enterprise Features
- Nested Job Support: Full support for Jenkins folder structures.
- 2FA Compatible: Can work with Jenkins two-factor authentication.
- Queue Management: Real-time build queue monitoring.
- Transport Flexibility: Supports both STDIO and streamable HTTP transports.
Requirements
- Node.js: Version 14.0.0 or higher.
- Python: Version 3.12 or higher.
- Jenkins: 2.401+ (recommended).
- Jenkins API Token: Required for authentication.
Installation and Configuration Installation is by cloning and installing. Automatically installed Python packages include: mcp[cli]>=1.11.0 (Model Context Protocol), requests>=2.32.4 (HTTP library), cachetools>=5.5.0 (caching tools), python-dotenv (environment variable management), pydantic (data validation), fastapi (HTTP transport support). A .env file needs to be created in the working directory.
Steps to obtain a Jenkins API Token: Log in to the Jenkins server; click the username → Configure;In the API Token area, click Add new Token; after naming it, click Generate; copy the generated token (it cannot be viewed again afterward).
A Claude Desktop integration method is provided, which needs to be added to claude_desktop_config.json.
Transport modes
- STDIO mode (default): standard input/output communication, best suited for Claude Desktop integration, no network port required.
- Streamable HTTP mode: HTTP-based communication, suitable for MCP Gateway or remote connections, requires port configuration.
Available tools (21 MCP tools in total) Task-related: trigger a job (supports parameters, job name, or path, such as "my-job" or "folder/my-job"); get job details (including job configuration, parameters, latest build information, and health status; when direct lookup fails, a pattern search can be performed); list jobs (supports filtering by recursion, maximum depth, whether to include folders, by color status, by build result such as SUCCESS/FAILURE/UNSTABLE, days since the last build, enabled jobs only, etc., returning a hierarchical job list with statistics); search jobs by pattern (supports wildcards, job type filtering job/folder/pipeline, regex matching, maximum search depth); search for and trigger all matching jobs; get folder information (such as "team/project"). Build status and monitoring: get the status of a specified build (build number, returning status, result, duration, timestamps, and executor information); get build console output (supports starting byte offset, returning log content and metadata); get a summarized version of the build console log. Pipeline support: get detailed pipeline execution status and stage information (returning the status, duration, and logs of each stage). Artifact management: list all artifacts of a certain build (including path, size, and download URL); download a specified build artifact (relative path, maximum download size defaults to 50 MB, binaries are returned encoded in base64); search artifacts across multiple builds (artifact name search pattern, maximum number of builds to search, regex matching). Batch operations: trigger multiple jobs in parallel with a priority queue (the operation list includes job names, optional parameters, and priority; the higher the value, the earlier it is executed; set the maximum concurrency, default 5; optional operation name; returns an operation ID for monitoring); monitor batch operation status (returns the status of each job by operation ID); cancel a batch operation (optionally also canceling ongoingon a running build). Queue and server management: retrieve Jenkins build queue information (job name, waiting time, and reason); retrieve basic Jenkins server information (version, root URL, and system information). Cache management: retrieve cache system statistics (hit/miss rate, size, and memory usage); clear cache data (you can specify a cache type such as static, dynamic, or specify a job name); prefill commonly used data to warm up the cache.
Cache system Implement a five-level cache system: static, semi-static, dynamic, short-term, permanent. Cache invalidation timing: when a job is triggered, when build status changes, and when the cache is manually cleared. Cache behavior can be customized via environment variables. Supports warm-up operations (such as list_jobs, server_info).
Error handling Provide detailed error information and suggestions: when 404 not found, provide similar job name search suggestions; when 401 unauthorized, prompt to check credentials; when 403 forbidden, explain the permission issue; on connection errors, automatically retry with exponential backoff.
Nested job support Full support for the Jenkins folder structure; all tools accept nested paths and handle them automatically.
Performance optimization Built-in optimizations include: multi-level intelligent caching, concurrent batch operations with throttling, request deduplication, lazy loading of large datasets, and configurable content size limits. Usage suggestions: use batch operations for multiple jobs; enable caching for repeated operations; set an appropriate max_depth when searching; use status_filter to reduce data transfer; warm up the cache before high-traffic periods.
Security Use Jenkins API Token authentication; support Jenkins 2FA environments; automatically handle CSRF crumb tokens. Security features: do not store passwords (only API tokens); support TLS/SSL for Jenkins HTTPS endpoints; perform input validation on all parameters; configurable artifact download size limits.
Troubleshooting Covers Python version errors, missing dependencies, connection refused (verify JENKINS_URL, whether Jenkins is running, network connectivity), authentication failures (regenerate the API token, verify JENKINS_USER, check permissions), and job not found (verify spelling and case, use search_jobs to find it, check access permissions). The server outputs logs to stderr with a request ID for troubleshooting.
License Apache License 2.0, see the LICENSE file for details. Version 1.0.7, last updated 2025-11-13.
