Jenkins MCP Tool

🚀 Introduction

Jenkins MCP is an multi-Jenkins server management and automation tool developed based on the FastMCP framework, designed for DevOps processes. It supports intelligent scenario mapping, multi-server management, complete CI/CD lifecycle operations, and dynamic job creation.

✨ Core Features

🏢 Multi-Server Management

• Dynamic Configuration: Supports configuration and dynamic addition/removal of multiple Jenkins servers

• Environment Isolation: Supports management of multiple environments such as development, testing, and production

• Secure Authentication: Supports token and environment variable-based authentication

🎯 Intelligent Scenario Mapping

• Pre-configured Scenarios: Built-in common DevOps scenarios (user permission sync, app deployment, image sync)

• Smart Recommendation: Automatically selects server and job path based on scenario

• Personalized Guidance: Each scenario provides customized operation guidance

⚙️ Full CI/CD Support

• Job Search: Supports fuzzy and exact search across multi-level directories

• Parameterized Build: Automatically detects and validates required parameters

• Real-time Monitoring: Build status query and log retrieval

• Build Control: Supports build trigger, stop, and management

• Job Creation: Create/update Jenkins jobs from Jenkinsfile with automatic directory management

🔧 Developer Friendly

• MCP Standard: Complies with Model Context Protocol specification

• Dockerized: Containerized deployment for easy integration

• Multiple Operation Modes: Supports stdio, SSE, and HTTP transport modes

⚙️ Configuration Guide

📁 Config File Structure

Create a config.yaml file to configure Jenkins servers and application scenarios:

🔐 Security Configuration

Recommended: Use environment variables to manage sensitive information

Configuration Priority:

1. Environment variable (variable name specified by tokenEnv)

2. Direct configuration (token field)

3. Interactive input (if neither is configured)

🚀 Quick Start

🐳 Docker Method (Recommended)

1. Build Image

2. Prepare Configuration

Create a config.yaml file (refer to the configuration guide above)

3. Run Container

🎨 MCP Client Integration

Cursor Integration

1. Set Environment Variables:

   export JENKINS_TOKEN="your-jenkins-token"

2. Create Config File: Create jenkins-config.yaml in the project root:

   servers: - name: your-jenkins uri: https://your-jenkins.company.com user: your-username tokenEnv: JENKINS_TOKEN scenarios: "Deploy Application": description: "Application deployment scenario" server: "your-jenkins" job_path: "deploy/"

3. Configure Cursor MCP Settings: Add to Cursor's MCP config:

   { "mcpServers": { "jenkins": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/to/your/jenkins-config.yaml:/app/config.yaml", "-e", "JENKINS_TOKEN=${JENKINS_TOKEN}", "docker.io/mpan083/jenkins-mcp" ], "env": { "JENKINS_TOKEN": "your-jenkins-token" } } } }

4. Usage Example: In Cursor, ask:

   "Get the list of available Jenkins scenarios" "Trigger a build for Deploy Application" "Check the status of the latest build" "Create a new test job from Jenkinsfile"

Method 2: Local Installation

1. Install Dependencies:

   cd mcps/jenkins pip install -e .

2. Configure Cursor MCP Settings:

   { "mcpServers": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "~/.jenkinscliconfig:/app/config.yaml", "docker.io/mpan083/jenkins-mcp" ] } } }

🔧 Command Line Arguments

Jenkins MCP supports the following command line arguments:

🔧 Traditional Startup

📋 Available Tools (11)

🔧 Server Management

🎯 Intelligent Scenarios (Recommended Workflow)

🔍 Job Search and Management

⚙️ Build Management

🚀 Job Creation and Management

🚀 Recommended Workflow

Scenario-based Deployment (Recommended)

General Job Search

Job Creation Workflow

💡 Usage Examples

Scenario-based Deployment Example

Direct Operation Example

Job Creation Example

🔍 Enhanced Job Information

When searching or getting job information, the following details are returned:

• Basic Info: Job name, full name, URL, description

• Status: Buildable status, color indicator, parameterization status

• Build History: Last build number, last build URL

• Parameters: Complete parameter definitions with types and default values

🏗️ Job Creation Features

Automatic Directory Management

• User Organization: All created jobs are organized under MCPS/{username}/ directory

• Username Extraction: Automatically extracts username from Jenkins server configuration (handles email formats)

• Folder Creation: Automatically creates necessary folder structure

• Nested Folders: Supports creating jobs in nested folder paths

Job Creation Process

1. Folder Structure: Jobs are created in MCPS/{username}/{optional_folder_path}/

2. Conflict Handling: Automatically detects existing jobs and updates configuration

3. Pipeline Jobs: Creates pipeline jobs with sandbox security enabled

4. Error Recovery: Robust error handling for folder creation and job updates

🎯 Pre-configured Scenarios

Jenkins MCP comes with 3 common DevOps scenarios:

🎨 Custom Scenario Configuration

📁 Scenario File Support

Jenkins MCP supports multiple ways to configure custom scenarios:

1. Standalone Scenario File (Recommended):

   # Create custom scenario file cp scenarios.example.yaml scenarios.yaml # Specify scenario file at startup jenkins --scenarios scenarios.yaml

2. Environment Variable:

   export JENKINS_MCP_SCENARIOS_FILE="/path/to/my-scenarios.yaml" jenkins

3. Configure in config.yaml:

   scenarios: "Custom Deployment": description: "Custom application deployment scenario" server: "your-jenkins" job_path: "custom/deploy/" prompt_template: "Execute custom deployment task. Please confirm deployment parameters?"

🔄 Scenario Merge Rules

• Default Scenarios: Load built-in scenarios from scenarios.default.yaml

• User Scenarios: Load from custom scenario file

• Merge Strategy: User scenarios take precedence, same-name scenarios override defaults

📝 Scenario File Example

Create a scenarios.yaml file:

🧪 Testing

Unit Tests

Docker Test

MCP Inspector Testing

🔧 Development

Local Development Environment

Contribution Guide

1. Fork this repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📚 Documentation

• Tool Documentation - Complete tool list and usage

• FastMCP Documentation - MCP framework docs

• Model Context Protocol - MCP protocol standard

🆘 Troubleshooting

Common Issues

Q: Failed to connect to Jenkins server?
A: Check network, URL, and authentication info. Use validate_jenkins_config() to validate config.

Q: Build parameter validation failed?
A: Use get_job_parameters() to check required parameters and ensure all are provided.

Q: Docker container failed to start?
A: Check config file mount path and environment variable settings.

Q: Job creation failed with 500 error?
A: Check Jenkins permissions and CSRF settings. The tool automatically handles CSRF tokens.

Q: Cannot create job in specified folder?
A: Ensure you have permission to create folders and jobs. Jobs are automatically organized under MCPS/{username}/.

Log Debugging

Performance Optimization

• Multi-level Directory Support: Efficiently handles nested Jenkins folders

• Intelligent Parameter Detection: Reduces API calls through smart caching

• CSRF Token Management: Automatic token handling for secure Jenkins instances

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

If you have questions or suggestions:

1. Check known issues in Issues

2. Create a new Issue to report problems

3. Contact the development team for support

Jenkins MCP - Make Jenkins automation easier 🚀