jenkins-mcp-server 0.1.0

A Python-based Jenkins MCP server using the Model Context Protocol Python SDK

Jenkins MCP Server

A Python-based Jenkins MCP server using the Model Context Protocol Python SDK. This server integrates with Jenkins CI/CD systems to provide AI-powered insights, build management, and debugging capabilities.

Note: This server follows the Model Context Protocol (MCP), enabling AI assistants to interact with Jenkins systems directly.

Installation

Option 1: Install as a Python Package (Recommended)

The easiest way to install and run this server is as a Python package:

# Install directly from GitHub
pip install git+https://github.com/yourusername/jenkins-mcp-server.git

# Run the server
jenkins-mcp-server --verbose

Option 2: Clone and Run

# Clone the repository
git clone https://github.com/yourusername/jenkins-mcp-server.git
cd jenkins-mcp-server

# Create a virtual environment and install dependencies
uv venv
uv pip install -e .

# Run the server
python -m jenkins_mcp_server

VS Code Integration

To use this MCP server in VS Code:

1. Install the MCP extension for VS Code
2. Configure your VS Code settings as shown below
3. Connect any AI assistant that supports MCP to your Jenkins environment

Components

Resources

The server provides access to Jenkins jobs as resources:

• Custom jenkins:// URI scheme for accessing individual jobs
• Each job resource contains details about the job and its builds in JSON format
• Job status is reflected in the resource description

Prompts

The server provides prompts for Jenkins data analysis:

1. analyze-job-status: Creates analysis of all Jenkins jobs

   • Optional "detail_level" argument to control analysis depth (brief/detailed)
   • Analyzes job statuses, identifies potential issues, and suggests improvements

2. analyze-build-logs: Analyzes build logs for a specific job

   • Required "job_name" argument to specify which job to analyze
   • Optional "build_number" argument (defaults to latest build)
   • Examines build logs to identify issues, errors, warnings, and suggests fixes

Tools

The server implements three tools for Jenkins operations:

1. trigger-build: Triggers a Jenkins job build

   • Required "job_name" argument to specify which job to build
   • Optional "parameters" object containing job parameters
   • Returns build queue information

2. stop-build: Stops a running Jenkins build

   • Required "job_name" and "build_number" arguments
   • Halts an in-progress build execution

3. get-job-details: Gets detailed information about a specific job

   • Required "job_name" argument
   • Returns comprehensive job information including recent builds

Configuration

Option 1: VS Code Settings (Recommended)

Configure your Jenkins connection in VS Code settings.json:

1. Open VS Code Settings (Press Cmd+, on Mac or Ctrl+, on Windows/Linux)
2. Click on the "Open Settings (JSON)" button in the top right
3. Add these settings:

"mcp.servers": {
  "jenkins-mcp-server": {
    "type": "stdio",
    "command": "uvx",
    "args": ["jenkins-mcp-server"]
  }
},
"jenkins-mcp-server.jenkins": {
  "url": "http://your-jenkins-server:8080",
  "username": "your-username",
  "token": "your-api-token"  // Recommended: use token instead of password
  // "password": "your-password"  // Alternative: use password
}

This configuration:

• Registers the MCP server in VS Code
• Stores your Jenkins credentials securely in VS Code settings
• Uses uvx to run the server automatically when needed

Option 2: Environment Variables

Alternatively, configure your Jenkins connection by setting environment variables:

1. Copy the .env.example file to create a .env file:

   cp .env.example .env
   

2. Edit the .env file with your Jenkins details:

   JENKINS_URL=http://your-jenkins-server:8080
   JENKINS_USERNAME=your-username
   JENKINS_PASSWORD=your-password
   # OR use an API token instead of password (recommended)
   JENKINS_TOKEN=your-api-token
   

Security Note: Using VS Code settings is more secure as they are stored encrypted. Environment variables in a .env file are stored in plain text.

Usage with AI Assistants

Once configured, AI assistants that support MCP can now interact with your Jenkins server through natural language. Here are some examples of what you can do:

GitHub Copilot Chat

1. Open GitHub Copilot Chat in VS Code
2. Type prompts like:
   • "List all my Jenkins jobs"
   • "What's the status of my 'deployment' job?"
   • "Show me the build logs for the failed build in 'test-project'"
   • "Trigger a new build for 'deploy-api'"

Command Line Usage

You can also run the server directly from the command line:

# Run the MCP server
uvx jenkins-mcp-server

# In another terminal, use curl to test it:
curl -X POST http://localhost:8080/mcp/v1/listResources -H "Content-Type: application/json" -d '{}'

Command-Line Usage

The uvx command makes it easy to use the MCP server in command-line environments without VS Code:

# Install UVX if you don't have it yet
pip install uv

# Install the Jenkins MCP server
uvx install git+https://github.com/yourusername/jenkins-mcp-server.git

# Run the server with verbose output
uvx jenkins-mcp-server --verbose

Testing from Command Line

You can test the server directly using the included demo script:

# Run the demo script
./demo.py

Or manually send JSON-RPC requests:

echo '{"jsonrpc":"2.0","id":1,"method":"listResources","params":{}}' | uvx jenkins-mcp-server

Development Setup

If you're developing this MCP server:

1. Clone this repository
2. Install dependencies:

   uv venv
   uv pip install -e ".[dev]"
   

3. Run the server in development mode:

   python -m jenkins_mcp_server --verbose
   

VS Code Configuration for Development

For development in VS Code:

"mcp": {
  "servers": {
    "jenkins-mcp-server": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c", 
        "uvx jenkins-mcp-server"
      ]
    }
  }
}

3. Install the GitHub Copilot Chat extension
4. Enable MCP in Copilot settings
5. Start a new chat with Copilot and interact with your Jenkins server!

3. Claude Desktop

For Claude Desktop users:

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development Configuration

"mcpServers": {
  "jenkins-mcp-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/Users/annmariyajoshy/vibecoding/jenkins-mcp-server-v2",
      "run",
      "jenkins-mcp-server"
    ]
  }
}

Published Configuration (using uvx)

"mcpServers": {
  "jenkins-mcp-server": {
    "command": "uvx",
    "args": [
      "jenkins-mcp-server"
    ]
  }
}

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/jenkins-mcp-server-v2 run jenkins-mcp-server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.