jenkins-mcp-server 0.1.6

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 from PyPI
pip install jenkins-mcp-server==0.1.5

# Or install with uv
uv pip install jenkins-mcp-server==0.1.5

# 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

Configure for VS Code

For quick installation, use one of the one-click install buttons below:

For manual installation:

1. Install the Model Context Protocol (MCP) extension for VS Code
2. Create a .vscode/mcp.json file in your workspace with the following configuration:

{
  "servers": {
    "jenkins-mcp-server": {
      "type": "stdio",
      "command": "jenkins-mcp-server",
      "args": ["--verbose"],
      "env": {
        "JENKINS_URL": "http://your-jenkins-server:8080",
        "JENKINS_USERNAME": "your-username",
        "JENKINS_TOKEN": "your-api-token"
        // Or use JENKINS_PASSWORD instead of JENKINS_TOKEN if using password authentication
      }
    }
  }
}

3. Configure your authentication method:

   • Recommended: Use API token authentication by setting JENKINS_TOKEN
   • Alternatively: Use password authentication by setting JENKINS_PASSWORD

4. Connect any AI assistant that supports MCP (like GitHub Copilot) 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 the following 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

4. list-jobs: Lists all Jenkins jobs

   • Returns a list of all Jenkins jobs with their statuses

5. get-build-info: Gets information about a specific build

   • Required "job_name" and "build_number" arguments
   • Returns build status, duration, and other details

6. get-build-console: Gets console output from a build

   • Required "job_name" and "build_number" arguments
   • Returns the console log output from a specific build

7. get-queue-info: Gets information about the Jenkins build queue

   • Returns information about pending builds in the queue

8. get-node-info: Gets information about a Jenkins node/agent

   • Required "node_name" argument
   • Returns node status and configuration details

9. list-nodes: Lists all Jenkins nodes/agents

   • Returns a list of all Jenkins nodes/agents and their statuses

Configuration

Option 1: VS Code Settings (Recommended)

Configure your Jenkins connection in VS Code settings:

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:

Using the User Settings (JSON)

{
  "mcp.servers": {
    "jenkins": {
      "type": "stdio",
      "command": "uvx",
      "args": ["jenkins-mcp-server"]
    }
  },
  "jenkins-mcp-server.jenkins": {
    "url": "http://your-jenkins-server:8080",
    "username": "your-username",
    "token": "********"  // Replace with your Jenkins API token
  }
}

Using workspace .vscode/mcp.json file

Create a file at .vscode/mcp.json with these contents:

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

And in your .vscode/settings.json file:

{
  "jenkins-mcp-server.jenkins": {
    "url": "http://your-jenkins-server:8080",
    "username": "your-username",
    "token": "********"  // Replace with your Jenkins API token
  }
}

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 jenkins-mcp-server

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

# Install the Jenkins MCP server from PyPI
uvx install jenkins-mcp-server==0.1.5

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

Testing from Command Line

You can 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", 
        "cd ${workspaceFolder} && python -m jenkins_mcp_server --verbose"
      ]
    }
  }
}

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": [
      "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:

# If installed globally with uvx
npx @modelcontextprotocol/inspector uvx jenkins-mcp-server

# If installed in development mode
npx @modelcontextprotocol/inspector python -m jenkins_mcp_server

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