jenkins-mcp-server

Jenkins MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Jenkins through various automation tools. This server provides comprehensive Jenkins management capabilities including job monitoring, build control, and queue management.

Features

• Job Management: List jobs, get job configurations, and monitor job status
• Build Control: Trigger builds with parameters, stop running builds, and check build status
• Build History: Retrieve build history and detailed build information
• Console Logs: Access build console output for debugging
• Queue Management: Monitor Jenkins build queue and stuck builds
• Folder Support: Navigate Jenkins folders and organizational structures

Installation

1. Clone the repository:

git clone https://github.com/ddang-jung/jenkins-mcp-server.git
cd jenkins-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

Set the following environment variables for Jenkins authentication:

• JENKINS_URL: Your Jenkins server URL (e.g., http://localhost:8080)
• JENKINS_USER: Your Jenkins username
• JENKINS_TOKEN: Your Jenkins API token (recommended) or password

Getting Jenkins API Token

1. Log into Jenkins
2. Go to Manage Jenkins → Manage Users → Click your username
3. Click Configure → API Token → Add new Token
4. Copy the generated token

Git Configuration

The project includes a comprehensive .gitignore file that excludes:

• Build artifacts (build/, dist/)
• Dependencies (node_modules/)
• Environment variables (.env*)
• Jenkins credentials and configuration files
• IDE files (.vscode/, .idea/)
• System files (.DS_Store, Thumbs.db)

Important: Never commit Jenkins credentials or API tokens to version control.

Claude Desktop Configuration

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "node",
      "args": ["/path/to/jenkins-mcp-server/build/index.js"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USER": "your-username",
        "JENKINS_TOKEN": "your-api-token"
      }
    }
  }
}

Usage

Starting the Server

npm start

The server runs on stdio and communicates with Claude through the MCP protocol.

Development Mode

For development with auto-rebuild:

npm run watch

For debugging with MCP Inspector:

npm run inspector

Available Tools

1. get_build_status

Get the status of a specific Jenkins build.

Parameters:

• jobPath (required): Path to the Jenkins job (e.g., "job/MyProject/job/main")
• buildNumber (optional): Build number or "lastBuild" for most recent

Example:

{
  "jobPath": "job/MyProject",
  "buildNumber": "lastBuild"
}

2. trigger_build

Trigger a new Jenkins build with optional parameters.

Parameters:

• jobPath (required): Path to the Jenkins job
• parameters (optional): Build parameters as key-value pairs

Example:

{
  "jobPath": "job/MyProject",
  "parameters": {
    "BRANCH": "main",
    "DEPLOY_ENV": "staging"
  }
}

3. get_build_log

Retrieve the console output of a specific build.

Parameters:

• jobPath (required): Path to the Jenkins job
• buildNumber (required): Build number or "lastBuild"

4. list_jobs

List all Jenkins jobs in a folder or at root level.

Parameters:

• folderPath (optional): Path to folder (e.g., "job/MyFolder") or empty for root

5. get_build_history

Get build history for a specific Jenkins job.

Parameters:

• jobPath (required): Path to the Jenkins job
• limit (optional): Number of recent builds to retrieve (default: 10)

6. stop_build

Stop a running Jenkins build.

Parameters:

• jobPath (required): Path to the Jenkins job
• buildNumber (required): Build number or "lastBuild"

7. get_queue

Get the current Jenkins build queue status.

Parameters: None

8. get_job_config

Get the configuration details of a Jenkins job.

Parameters:

• jobPath (required): Path to the Jenkins job

Job Path Format

Jenkins job paths follow this format:

• Root level job: job/JobName
• Folder job: job/FolderName/job/JobName
• Multi-level: job/Folder1/job/Folder2/job/JobName

Error Handling

The server provides comprehensive error handling:

• Authentication errors: Check your Jenkins credentials
• Job not found: Verify the job path format
• Permission errors: Ensure your Jenkins user has appropriate permissions
• Network errors: Check Jenkins server connectivity

Development

Project Structure

jenkins-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file

Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run watch: Watch for changes and rebuild
• npm run inspector: Start MCP Inspector for debugging
• npm run prepare: Prepare build (runs automatically)
• npm run clean: Clean build artifacts and dependencies (macOS/Linux)
• npm run clean:win: Clean build artifacts and dependencies (Windows)

Cleaning Project

To reset the project to its initial state (remove build artifacts and dependencies):

macOS/Linux:

npm run clean
# or manually:
rm -rf node_modules build package-lock.json

Windows:

npm run clean:win
# or manually:
rmdir /s /q node_modules & rmdir /s /q build & del package-lock.json

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License.

Troubleshooting

Common Issues

1. "Jenkins API error": Check your Jenkins URL and credentials
2. "Job not found": Verify the job path format (use job/ prefix)
3. "Permission denied": Ensure your Jenkins user has required permissions
4. "Connection refused": Check if Jenkins server is running and accessible

Debug Mode

Enable debug logging by setting:

export DEBUG=jenkins-mcp-server

For more information, visit the Jenkins REST API documentation.