# 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)](https://modelcontextprotocol.io/), 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:

```bash
# 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

```bash
# 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:

```json
"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:
   ```bash
   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:

```bash
# 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:

```bash
# 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:

```bash
# Run the demo script
./demo.py
```

Or manually send JSON-RPC requests:

```bash
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:
   ```bash
   uv venv
   uv pip install -e ".[dev]"
   ```
3. Run the server in development mode:
   ```bash
   python -m jenkins_mcp_server --verbose
   ```

### VS Code Configuration for Development

For development in VS Code:

```json
"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`

<details>
  <summary>Development Configuration</summary>
  
  ```json
  "mcpServers": {
    "jenkins-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/annmariyajoshy/vibecoding/jenkins-mcp-server-v2",
        "run",
        "jenkins-mcp-server"
      ]
    }
  }
  ```
</details>

<details>
  <summary>Published Configuration (using uvx)</summary>
  
  ```json
  "mcpServers": {
    "jenkins-mcp-server": {
      "command": "uvx",
      "args": [
        "jenkins-mcp-server"
      ]
    }
  }
  ```
</details>

## Development

### Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:
```bash
uv sync
```

2. Build package distributions:
```bash
uv build
```

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

3. Publish to PyPI:
```bash
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](https://github.com/modelcontextprotocol/inspector).


You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:

```bash
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.