README.md•4.97 kB
# Jenkins MCP Server
🚀 AI-powered Jenkins management via Model Context Protocol. Trigger builds, manage jobs, and monitor CI/CD pipelines through your favorite AI assistant.
## � Installation
### Option 1: Global Installation (Recommended)
```bash
npm install -g jenkins-mcp-server
```
### Option 2: Local Installation
```bash
npm install jenkins-mcp-server
```
### Option 3: Use with npx (No Installation)
```bash
npx jenkins-mcp-server
```
## ⚙️ Configuration
Set required environment variables:
```bash
export JENKINS_URL="http://your-jenkins-instance:8080"
export JENKINS_USERNAME="your-username"
export JENKINS_API_TOKEN="your-api-token"
```
### Getting Jenkins API Token
1. Login to Jenkins → Click your username → Configure
2. Under "API Token" → Add new Token → Generate
3. Copy the token and use it as `JENKINS_API_TOKEN`
## 🤖 MCP Client Setup
### GitHub Copilot (VS Code)
Add to `mcp.json`:
```json
{
"servers": {
"jenkins": {
"command": "npx",
"args": ["jenkins-mcp-server"],
"env": {
"JENKINS_URL": "http://your-jenkins-instance:8080",
"JENKINS_USERNAME": "your-username",
"JENKINS_API_TOKEN": "your-api-token"
// "ALLOW_ABSOLUTE_FILE_PARAMS": 1 // for file parameters with absolute paths
}
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"jenkins": {
"command": "npx",
"args": ["jenkins-mcp-server"],
"env": {
"JENKINS_URL": "http://your-jenkins-instance:8080",
"JENKINS_USERNAME": "your-username",
"JENKINS_API_TOKEN": "your-api-token",
// "ALLOW_ABSOLUTE_FILE_PARAMS": 1 // for file parameters with absolute paths
}
}
}
}
```
## 🛠️ Available Tools
Each tool returns a JSON result with `success` plus additional fields. Provide arguments as an object when invoking via an MCP client.
### Build Management
**triggerBuild** – Start a job build (supports file + regular parameters)
Inputs:
- `jobFullName` (string, required)
- `parameters` (object, optional) – Key/value map. Any value that is a valid local file path is uploaded as a file parameter.
**File Parameter Security**: By default, only relative file paths are allowed. To enable absolute file paths, set `ALLOW_ABSOLUTE_FILE_PARAMS=1` in your environment variables.
Returns: `{ success, queueId, queueUrl, statusCode, message }`
**stopBuild** – Stop (or force kill) the running build
Inputs:
- `jobFullName` (string, required)
- `buildNumber` (integer, optional)
Returns: `{ success, action: "stop"|"kill", buildNumber, buildUrl, message }`
**scheduleBuild** – Schedule a build in the future
Inputs:
- `jobFullName` (string, required)
- `scheduleTime` (string, required) – e.g. `22:15`, `10:30 PM`, or `2025-12-24 14:30`
- `parameters` (object, optional)
**File Parameter Security**: By default, only relative file paths are allowed. To enable absolute file paths, set `ALLOW_ABSOLUTE_FILE_PARAMS=1` in your environment variables.
Returns: `{ status, queueUrl }`
**updateBuild** – Update build description (display name not supported via REST)
Inputs:
- `jobFullName` (string, required)
- `buildNumber` (integer, optional)
- `description` (string, optional)
- `displayName` (string, optional, ignored)
Returns: `{ success, buildNumber, updates: [ { field, success, ... } ] }`
### Job Information
**getJob** – Job metadata
Inputs: `jobFullName` (string, required)
**getBuild** – Build details (specific or last)
Inputs:
- `jobFullName` (string, required)
- `buildNumber` (integer, optional)
**getJobs** – Paginated job list
Inputs:
- `parentFullName` (string, optional)
- `skip` (integer, optional, default 0)
- `limit` (integer, optional, default 10, max 10)
### System Monitoring
**whoAmI** – Current authenticated user
Inputs: none
**getStatus** – Jenkins instance status / health
Inputs: none
### Artifact Management
**listBuildArtifacts** – List artifacts for build
Inputs:
- `jobFullName` (string, required)
- `buildNumber` (integer, optional)
**readBuildArtifact** – Read artifact content (text or base64)
Inputs:
- `jobFullName` (string, required)
- `artifactPath` (string, required)
- `buildNumber` (integer, optional)
- `format` (string, optional: `text` | `base64`)
### Queue Operations
**cancelQueuedBuild** – Cancel queued item(s)
Inputs:
- `jobFullName` (string, required)
- `queueId` (integer, optional)
**getQueueInfo** – List queued builds (optionally filtered)
Inputs:
- `jobFullName` (string, optional)
Tip: Ask your AI assistant: "Trigger a build for job X with BRANCH=main" or "List artifacts for latest job X build".
## ⚡ Usage
After configuration, ask your AI assistant:
- "Check my Jenkins server status"
- "Trigger a build for my-app"
- "Show me the latest build information"
- "List all Jenkins jobs"
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
---