Jenkins MCP Server

A comprehensive Jenkins Model Context Protocol (MCP) server that provides tools for managing Jenkins builds, jobs, artifacts, and queue operations through the MCP interface.

📋 Table of Contents

🚀 Features

Build Management: Trigger, stop, schedule, and update Jenkins builds
Job Information: Retrieve comprehensive job and build information
System Monitoring: Get Jenkins instance status and health information
Artifact Management: List and read build artifacts
Queue Operations: Manage and monitor build queues
CSRF Protection: Automatic handling of Jenkins CSRF tokens
Authentication: Support for Jenkins API tokens and basic auth

🏗️ Architecture

The codebase is organized into a modular, scalable structure:

src/
├── index.js                 # Main entry point
├── client/
│   └── jenkins-client.js    # Jenkins HTTP client with auth & CSRF
├── server/
│   └── mcp-server.js        # MCP server implementation
├── tools/
│   ├── index.js             # Tool registry and management
│   ├── build-management.js  # Build-related operations
│   ├── job-info.js          # Job information retrieval
│   ├── system-info.js       # System status and user info
│   ├── artifact-management.js # Artifact operations
│   └── queue-management.js  # Queue operations
├── config/
│   └── index.js             # Configuration management
└── utils/
    └── jenkins.js           # Utility functions

📦 Installation

Clone the repository:
git clone <repository-url> cd jenkins-mcp
Install dependencies:
npm install
Configure environment variables (see Configuration)
Start the server:
npm start
Or for development with auto-restart:
npm run dev

⚙️ Configuration

Configure the server using environment variables:

# Required: Jenkins instance URL
export JENKINS_URL="http://your-jenkins-instance:8080"

# Required: Jenkins username
export JENKINS_USER="your-username"

# Required: Jenkins API token (recommended)
export JENKINS_API_TOKEN="your-api-token"

Getting a Jenkins API Token

Log into your Jenkins instance
Click on your username (top right) → Configure
Under "API Token", click "Add new Token"
Give it a name and click "Generate"
Copy the generated token and use it as JENKINS_API_TOKEN

MCP Client Configuration

This Jenkins MCP Server can be integrated with various MCP clients. Here's how to configure it with popular clients:

🤖 GitHub Copilot (VS Code)

Install the MCP extension in VS Code
Add to your mcp.json:
{ "servers": { "jenkins": { "command": "node", "args": ["path/to/jenkins-mcp/src/index.js"], "env": { "JENKINS_URL": "http://your-jenkins-instance:8080", "JENKINS_USER": "your-username", "JENKINS_API_TOKEN": "your-api-token" } } } }

🧠 Claude Desktop

Edit Claude's config file (~/.config/claude-desktop/claude_desktop_config.json):
{ "mcpServers": { "jenkins": { "command": "node", "args": ["path/to/jenkins-mcp/src/index.js"], "env": { "JENKINS_URL": "http://your-jenkins-instance:8080", "JENKINS_USER": "your-username", "JENKINS_API_TOKEN": "your-api-token" } } } }

⚡ EliteA MCP Client

Add to EliteA configuration(config.json):
{ "servers": { "jenkins-mcp": { "type": "stdio", "command": "node", "args": ["path/to/jenkins-mcp/src/index.js"], "environment": { "JENKINS_URL": "http://your-jenkins-instance:8080", "JENKINS_USER": "your-username", "JENKINS_API_TOKEN": "your-api-token" } } } }

Important Notes:

Replace path/to/jenkins-mcp/src/index.js with the actual absolute path to your installation
Ensure Node.js is in your system PATH
The server communicates via stdin/stdout following the MCP protocol
All Jenkins tools will be available once configured

🛠️ Available Tools

Build Management

`triggerBuild`

Trigger a build for a Jenkins job.

jobFullName (string, required): Full path of the Jenkins job
parameters (object, optional): Build parameters

`stopBuild`

Stop or kill a running Jenkins build.

jobFullName (string, required): Full path of the Jenkins job
buildNumber (integer, optional): Build number to stop (defaults to last build)

`scheduleBuild`

Schedule a Jenkins build to run at a specific time.

jobFullName (string, required): Full path of the Jenkins job
scheduleTime (string, required): Time to schedule (e.g., '22:15', '10:30 PM')
parameters (object, optional): Build parameters

`updateBuild`

Update build display name and/or description.

jobFullName (string, required): Full path of the Jenkins job
buildNumber (integer, optional): Build number (defaults to last build)
displayName (string, optional): New display name
description (string, optional): New description

Job Information

`getJob`

Get information about a Jenkins job.

jobFullName (string, required): Full path of the Jenkins job

`getBuild`

Get information about a specific build or the last build.

jobFullName (string, required): Full path of the Jenkins job
buildNumber (integer, optional): Build number (defaults to last build)

`getJobs`

Get a paginated list of Jenkins jobs.

parentFullName (string, optional): Full path of the parent folder
skip (integer, optional): Number of items to skip (default: 0)
limit (integer, optional): Maximum items to return (default: 10, max: 10)

System Information

`whoAmI`

Get information about the current authenticated user.

`getStatus`

Get Jenkins instance status and health information.

Artifact Management

`listBuildArtifacts`

List all artifacts from a specific build or the last build.

jobFullName (string, required): Full path of the Jenkins job
buildNumber (integer, optional): Build number (defaults to last build)

`readBuildArtifact`

Read the content of a specific build artifact.

jobFullName (string, required): Full path of the Jenkins job
artifactPath (string, required): Relative path to the artifact
buildNumber (integer, optional): Build number (defaults to last build)
format (string, optional): Format for binary files ('text' or 'base64')

Queue Management

`cancelQueuedBuild`

Cancel a pending/queued Jenkins build that hasn't started yet.

jobFullName (string, required): Full path of the Jenkins job
queueId (integer, optional): Specific queue item ID to cancel

`getQueueInfo`

Get information about queued builds.

jobFullName (string, optional): Full path of the Jenkins job (returns all if not provided)

💡 Usage Examples

Triggering a Build

{
	"tool": "triggerBuild",
	"arguments": {
		"jobFullName": "my-project/main-build",
		"parameters": {
			"BRANCH": "main",
			"ENVIRONMENT": "staging"
		}
	}
}

Getting Build Information

{
	"tool": "getBuild",
	"arguments": {
		"jobFullName": "my-project/main-build",
		"buildNumber": 123
	}
}

Reading an Artifact

{
	"tool": "readBuildArtifact",
	"arguments": {
		"jobFullName": "my-project/main-build",
		"artifactPath": "target/test-results.xml",
		"format": "text"
	}
}

Scheduling a Build

{
	"tool": "scheduleBuild",
	"arguments": {
		"jobFullName": "my-project/nightly-build",
		"scheduleTime": "22:30",
		"parameters": {
			"FULL_TEST": "true"
		}
	}
}

🔧 Development

Adding New Tools

Create the tool function in the appropriate file under src/tools/
Add the tool definition to src/tools/index.js in the toolRegistry
Update the README with the new tool documentation

Example tool structure:

export async function myNewTool(client, param1, param2) {
	try {
		// Tool implementation
		const result = await client.get("/some/endpoint");
		return {
			success: true,
			data: result.data,
		};
	} catch (error) {
		return formatError(error, "my operation");
	}
}

Project Structure Explained

src/client/: HTTP client for Jenkins API communication
src/server/: MCP server implementation and request handling
src/tools/: Individual tool implementations organized by functionality
src/config/: Configuration management and environment variables
src/utils/: Shared utility functions

Code Style

Use ES6+ features and async/await
Follow consistent error handling patterns
Include JSDoc comments for functions
Use descriptive variable and function names
Maintain modular structure for scalability

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🆘 Troubleshooting

Common Issues

Authentication Errors

Ensure JENKINS_API_TOKEN is correctly set
Verify the token has appropriate permissions
Check if the Jenkins user has access to the jobs

CSRF Token Issues

The server automatically handles CSRF tokens
Ensure Jenkins CSRF protection is enabled
For older Jenkins versions, you may need to disable CSRF protection

Connection Issues

Verify JENKINS_URL is accessible
Check firewall settings
Ensure Jenkins is running and responding

Tool Execution Errors

Check job names and paths are correct
Verify build numbers exist
Ensure proper permissions for the requested operations

For more specific issues, enable debug logging by setting:

export DEBUG=jenkins-mcp:*

Made with ❤️ by Utkarsh Mishra