@kud/mcp-jenkins

v0.2.0

Published

10 days ago

Jenkins MCP server with bearer token authentication support

Downloads

178

0High
0Medium
0Low

kud

jenkins mcp mcp-server automation ci-cd

Jenkins MCP Server

     ██╗███████╗███╗   ██╗██╗  ██╗██╗███╗   ██╗███████╗    ███╗   ███╗ ██████╗██████╗
     ██║██╔════╝████╗  ██║██║ ██╔╝██║████╗  ██║██╔════╝    ████╗ ████║██╔════╝██╔══██╗
     ██║█████╗  ██╔██╗ ██║█████╔╝ ██║██╔██╗ ██║███████╗    ██╔████╔██║██║     ██████╔╝
██   ██║██╔══╝  ██║╚██╗██║██╔═██╗ ██║██║╚██╗██║╚════██║    ██║╚██╔╝██║██║     ██╔═══╝
╚█████╔╝███████╗██║ ╚████║██║  ██╗██║██║ ╚████║███████║    ██║ ╚═╝ ██║╚██████╗██║
 ╚════╝ ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝╚══════╝    ╚═╝     ╚═╝ ╚═════╝╚═╝

A Jenkins MCP server with 25+ tools for managing jobs, builds, and CI/CD workflows

Features • Quick Start • Installation • Tools • Development

🌟 Features

🔐 Flexible Authentication - Bearer tokens, Basic auth, OAuth support
⚙️ Flexible Configuration - CLI args, MCP_JENKINS_, or JENKINS_ env vars (priority-based)
🛠️ 25+ Tools - Complete Jenkins API coverage
⚡ Modern Stack - TypeScript 5.3+, ES2023, Native Fetch API
📦 MCP Protocol - Native integration with Claude Desktop, Claude Code CLI
🔄 Real-time Monitoring - Build status, queue management, pipeline stages
🧪 Test Results - View test pass/fail counts and suites
🎯 Job Control - Enable/disable, trigger, stop, replay builds
📊 System Info - Nodes, plugins, version info
🔍 Debug Tools - MCP inspector for testing

🚀 Quick Start

Prerequisites

Node.js 20+
Jenkins API token (how to get one)

Installation

Option 1: Via npm (recommended once published):

# No installation needed! Just use npx in your MCP config
npx --yes @kud/mcp-jenkins@latest

Option 2: Local installation:

git clone https://github.com/yourusername/mcp-jenkins.git
cd mcp-jenkins
npm install
npm run build

Configuration Priority

The server supports 3 ways to provide configuration (highest to lowest priority):

CLI arguments - --url, --user, --api-token, --bearer-token
MCP_JENKINS_* environment variables - MCP_JENKINS_URL, MCP_JENKINS_USER, etc.
JENKINS_* environment variables - JENKINS_URL, JENKINS_USER, etc.

Quick Setup Example (Claude CLI)

Using CLI arguments (recommended for AI assistants like Copilot):

claude mcp add --transport stdio --scope user jenkins \
  -- npx --yes @kud/mcp-jenkins@latest \
  --url https://your-jenkins.com \
  --user your_username \
  --api-token your_token

Using environment variables:

claude mcp add --transport stdio --scope user jenkins \
  --env JENKINS_URL=https://your-jenkins.com \
  --env JENKINS_USER=your_username \
  --env JENKINS_API_TOKEN=your_token \
  -- npx --yes @kud/mcp-jenkins@latest

If installed locally:

claude mcp add --transport stdio --scope user jenkins \
  -- node ~/path/to/mcp-jenkins/dist/index.js \
  --url https://your-jenkins.com \
  --user your_username \
  --api-token your_token

✅ Done! Now you can use Jenkins commands in your AI assistant.

📚 Installation Guides

Choose your development environment:

Claude Code CLI - Command line interface
Claude Code Web - Browser-based Claude
Claude Desktop - Desktop application
VSCode - With Cline, Claude Dev, Continue
Cursor - AI-first IDE
Windsurf - AI-powered code editor
GitHub Copilot - In VSCode or standalone
GitHub Copilot CLI - Terminal tool
JetBrains IDEs - IntelliJ, WebStorm, PyCharm, GoLand, etc.

🎯 Claude Code CLI

For: Claude AI via command line interface

Add the Jenkins MCP server to Claude CLI:

Via npm with CLI args (recommended):

claude mcp add --transport stdio --scope user jenkins \
  -- npx --yes @kud/mcp-jenkins@latest \
  --url https://pipeline.yourcompany.com \
  --user your_username \
  --api-token your_api_token

Via npm with env vars:

claude mcp add --transport stdio --scope user jenkins \
  --env JENKINS_URL=https://pipeline.yourcompany.com \
  --env JENKINS_USER=your_username \
  --env JENKINS_API_TOKEN=your_api_token \
  -- npx --yes @kud/mcp-jenkins@latest

Local installation with CLI args:

claude mcp add --transport stdio --scope user jenkins \
  -- node $HOME/path/to/mcp-jenkins/dist/index.js \
  --url https://pipeline.yourcompany.com \
  --user your_username \
  --api-token your_api_token

Verify: claude mcp list should show jenkins

🌐 Claude Code Web

For: Claude.ai in your browser

⚠️ Not supported. Claude.ai web interface doesn't support custom MCP servers yet.

Alternatives:

Use desktop clients (see below)
Use CLI tools (see above)
Test via MCP Inspector: npm run inspect:dev → http://localhost:5173

🖥️ Claude Desktop

For: Claude AI desktop application

1. Open Configuration File

macOS:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

2. Add Configuration

Via npm with CLI args (recommended):

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "--yes", "@kud/mcp-jenkins@latest",
        "--url", "https://pipeline.yourcompany.com",
        "--user", "your_username",
        "--api-token", "your_api_token"
      ]
    }
  }
}

Via npm with env vars:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "JENKINS_URL": "https://pipeline.yourcompany.com",
        "JENKINS_USER": "your_username",
        "JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

Local installation with CLI args:

{
  "mcpServers": {
    "jenkins": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-jenkins/dist/index.js",
        "--url", "https://pipeline.yourcompany.com",
        "--user", "your_username",
        "--api-token", "your_api_token"
      ]
    }
  }
}

Bearer token example:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "--yes", "@kud/mcp-jenkins@latest",
        "--url", "https://pipeline.yourcompany.com",
        "--bearer-token", "your_bearer_token"
      ]
    }
  }
}

3. Restart

Quit (Cmd+Q / Alt+F4) and reopen Claude Desktop

📝 VSCode

For: VSCode with MCP-compatible extensions (Cline, Claude Dev, Continue)

Cline:

Settings (Cmd+, / Ctrl+,) → Search "Cline: MCP Settings" → Edit in settings.json:

{
  "cline.mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["@kud/mcp-jenkins"],
      "env": {
        "JENKINS_URL": "https://pipeline.yourcompany.com",
        "JENKINS_USER": "your_username",
        "JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

Or for local installation, use "command": "node" and "args": ["/absolute/path/to/mcp-jenkins/dist/index.js"]

Claude Dev / Continue:

Command Palette (Cmd+Shift+P) → "MCP: Edit Config" → Add similar configuration

Reload window after configuration

🌐 Cursor

For: Cursor IDE with built-in AI

Settings (Cmd+, / Ctrl+,) → Search "MCP" → Edit Config or open ~/.cursor/mcp_config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "JENKINS_URL": "https://pipeline.yourcompany.com",
        "JENKINS_USER": "your_username",
        "JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

Or for local installation, use "command": "node" and "args": ["/absolute/path/to/mcp-jenkins/dist/index.js"]

Restart Cursor (Cmd+Q / Alt+F4) after configuration

🌊 Windsurf

For: Windsurf AI-powered code editor

Settings → AI Settings → Model Context Protocol → Add Server:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "JENKINS_URL": "https://pipeline.yourcompany.com",
        "JENKINS_USER": "your_username",
        "JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

Or edit ~/.windsurf/mcp_settings.json directly. For local installation, use "command": "node" with full path.

Restart Windsurf after configuration.

🤖 GitHub Copilot

For: GitHub Copilot in VSCode or other editors

⚠️ Not supported. GitHub Copilot doesn't support MCP servers.

Options:

In VSCode: Install Copilot + Cline/Claude Dev. Use Copilot for coding, Cline/Claude Dev for Jenkins (see VSCode section)
In terminal: Use Copilot for coding suggestions, an MCP-compatible CLI for Jenkins (see CLI sections above)
No MCP: Use code in src/lib/jenkins-client.ts as examples for direct API calls

💻 GitHub Copilot CLI

For: New GitHub Copilot CLI (@github/copilot) in your terminal

Note: This is for the NEW Copilot CLI (npm install -g @github/copilot), not the old gh copilot extension.

Option 1: Config File with CLI Args (Recommended)

Create or edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "--yes", "@kud/mcp-jenkins@latest",
        "--url", "https://pipeline.yourcompany.com",
        "--user", "your_username",
        "--api-token", "your_api_token"
      ]
    }
  }
}

Then run: copilot

Option 2: Config File with Env Vars

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "JENKINS_URL": "https://pipeline.yourcompany.com",
        "JENKINS_USER": "your_username",
        "JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

Option 3: Inline Config with CLI Args

Pass MCP config directly via command line:

copilot --additional-mcp-config '{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "--yes", "@kud/mcp-jenkins@latest",
        "--url", "https://pipeline.yourcompany.com",
        "--user", "your_username",
        "--api-token", "your_api_token"
      ]
    }
  }
}'

Or save to a file and reference it:

# Save config to jenkins-mcp.json
copilot --additional-mcp-config @jenkins-mcp.json

For local installation, use "command": "node" with path in args:

"args": ["/absolute/path/to/mcp-jenkins/dist/index.js", "--url", "...", "--user", "...", "--api-token", "..."]

Option 4: Allow All Tools (Non-Interactive)

For scripts and automation:

copilot --allow-all-tools -p "Check status of mobile-pipeline build"

🔧 All JetBrains IDEs

For: IntelliJ IDEA, WebStorm, PyCharm, GoLand, RubyMine, PhpStorm, Rider, CLion, DataGrip

Settings (Cmd+, / Ctrl+,) → Tools → AI Assistant → Model Context Protocol → Add Server:

Name: Jenkins
Command: npx
Arguments: --yes @kud/mcp-jenkins@latest

Environment Variables:

JENKINS_URL=https://pipeline.yourcompany.com
JENKINS_USER=your_username
JENKINS_API_TOKEN=your_api_token

For local installation, use Command: node and Arguments: /absolute/path/to/mcp-jenkins/dist/index.js

Apply and restart the IDE.

Alternative: If MCP not available, use MCP-compatible CLI from built-in terminal (Alt+F12 / ⌥F12)

Notes:

Ultimate/Professional editions: Full AI Assistant MCP support
Community editions: Use MCP-compatible CLI from terminal instead

🛠️ Available Tools

📋 Job Operations (5 tools)

| Tool | Description | |------|-------------| | jenkins_list_jobs | List all Jenkins jobs | | jenkins_search_jobs | Search jobs by name | | jenkins_get_job_status | Get last build status | | jenkins_enable_job | Enable a disabled job | | jenkins_disable_job | Disable a job | | jenkins_delete_job | Delete a job (⚠️ permanent) | | jenkins_get_job_config | Get job XML configuration |

🔨 Build Operations (9 tools)

| Tool | Description | |------|-------------| | jenkins_get_build_status | Get specific build status | | jenkins_get_recent_builds | Get recent builds (last N) | | jenkins_trigger_build | Trigger a new build | | jenkins_stop_build | Stop/abort running build | | jenkins_delete_build | Delete a build | | jenkins_replay_build | Replay a pipeline build | | jenkins_get_console_log | Get build console output | | jenkins_get_build_changes | Get Git commits for build | | jenkins_get_pipeline_stages | Get pipeline stage status |

🧪 Testing & Artifacts (3 tools)

| Tool | Description | |------|-------------| | jenkins_get_test_results | Get test pass/fail counts | | jenkins_list_artifacts | List build artifacts | | jenkins_get_artifact | Download artifact (base64) |

📊 Queue Management (2 tools)

| Tool | Description | |------|-------------| | jenkins_get_queue | View pending builds | | jenkins_cancel_queue | Cancel queued build |

🖥️ System Information (5 tools)

| Tool | Description | |------|-------------| | jenkins_list_nodes | List all agents/nodes | | jenkins_get_system_info | Get Jenkins system info | | jenkins_get_version | Get Jenkins version | | jenkins_get_plugins | List installed plugins |

Total: 25 Tools covering ~90% of Jenkins API operations!

💬 Example Conversations

Once configured, interact with Jenkins naturally:

You: "List all my Jenkins jobs"
AI: *Shows list of all jobs*

You: "What's the status of the 'api-backend' build?"
AI: *Shows latest build status, duration, result*

You: "Get the test results for build #42 of 'mobile-pipeline'"
AI: *Shows pass/fail counts, test suites*

You: "Show me the pipeline stages for that failed build"
AI: *Shows which stage failed and durations*

You: "Trigger a build for 'deploy-staging' with VERSION=2.1.0"
AI: *Triggers build with parameters*

You: "Stop build #966 of 'mobile-pipeline'"
AI: *Stops the running build*

You: "Show me the queue"
AI: *Lists all pending builds*

You: "What version of Jenkins are we running?"
AI: *Shows Jenkins version*

🧪 Development

Project Structure

mcp-jenkins/
├── src/
│   ├── common/              # Shared utilities
│   │   ├── env.ts           # Environment config
│   │   ├── errors.ts        # Error handling
│   │   ├── http.ts          # HTTP client (native fetch)
│   │   ├── logger.ts        # JSON logging
│   │   └── index.ts         # Exports
│   ├── lib/
│   │   └── jenkins-client.ts  # Jenkins API client
│   ├── tools/               # 25 MCP tool implementations
│   │   ├── get-job-status.ts
│   │   ├── trigger-build.ts
│   │   ├── get-test-results.ts
│   │   ├── stop-build.ts
│   │   └── ... (21 more)
│   └── index.ts             # MCP server entrypoint
├── dist/                    # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Available Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run build:watch | Watch mode - rebuild on changes | | npm run dev | Run in development (tsx) | | npm start | Run compiled server | | npm run inspect | Open MCP inspector | | npm run inspect:dev | Inspector in dev mode (no build) | | npm run typecheck | Type check without building | | npm run clean | Remove build artifacts |

Development Workflow

# Terminal 1: Watch mode
npm run build:watch

# Terminal 2: Test with inspector
npm run inspect:dev

Testing with MCP Inspector

export JENKINS_URL=https://pipeline.yourcompany.com
export JENKINS_USER=your_username
export JENKINS_API_TOKEN=your_token

npm run inspect:dev

Opens http://localhost:5173 - test all tools interactively!

Adding New Tools

Create tool file in src/tools/:

// src/tools/my-new-tool.ts
import { JenkinsClient } from '../lib/jenkins-client.js';

export interface MyToolInput {
  someParam: string;
}

export const myNewTool = async (client: JenkinsClient, input: MyToolInput) => {
  // Implementation
  return { result: 'success' };
};

Add method to JenkinsClient (src/lib/jenkins-client.ts)
Register in src/index.ts:
- Import the tool
- Add to tools array
- Add to toolHandlers map
Rebuild:

npm run build

⚙️ Configuration

Priority System

The server uses a 3-tier priority system for configuration:

CLI Arguments (Highest Priority)
- --url <url> - Jenkins server URL
- --user <username> - Username for Basic auth
- --api-token <token> - API token for Basic auth
- --bearer-token <token> - Bearer token for OAuth/token auth
MCP_JENKINS_ Environment Variables* (Medium Priority)
- MCP_JENKINS_URL
- MCP_JENKINS_USER
- MCP_JENKINS_API_TOKEN
- MCP_JENKINS_BEARER_TOKEN
JENKINS_ Environment Variables* (Lowest Priority)
- JENKINS_URL
- JENKINS_USER
- JENKINS_API_TOKEN
- JENKINS_BEARER_TOKEN

Why This Matters

This priority system allows you to:

Mix sources: Use CLI args for URL but env vars for credentials
Override easily: CLI args always win, great for testing different servers
Namespace safely: MCP_JENKINS_* vars won't conflict with other Jenkins tools

Examples

All CLI args:

node dist/index.js --url https://jenkins.com --user admin --api-token abc123

Mixed (CLI overrides env):

JENKINS_USER=dev_user node dist/index.js --url https://jenkins.com --api-token xyz789
# Uses: URL from CLI, token from CLI, user from env

All env vars with priority:

JENKINS_URL=https://fallback.com \
MCP_JENKINS_URL=https://primary.com \
node dist/index.js
# Uses: https://primary.com (MCP_JENKINS_* wins)

🔐 Authentication

Get Your Jenkins API Token

Follow these steps to create an API token for the MCP server:

Step 1: Access Security Settings

Log in to your Jenkins instance
Click your username in the top-right corner
Select Configure from the dropdown menu
In the left sidebar, click Security

Step 2: Create API Token

Scroll to the API Token section
Under "Current token(s)", click the Add new token button
Enter a descriptive name (e.g., "Jenkins MCP" or "AI Assistant")
Click Generate
⚠️ IMPORTANT: Copy the token immediately - it will only be shown once!

Step 3: Save the Token

Store the token securely - you'll need it for configuration:

For Bearer Token auth: Use it as JENKINS_BEARER_TOKEN
For Basic auth: Use it as JENKINS_API_TOKEN (along with JENKINS_USER)

Example token format: 11abcd1234567890abcdef1234567890ab

💡 Tip: You can see all your active tokens in the "Current token(s)" list. Each shows when it was created and last used, helping you manage and rotate tokens regularly.

Bearer Token vs Basic Auth

Bearer Token (Recommended):

--env JENKINS_BEARER_TOKEN=your_token

Basic Auth:

--env JENKINS_USER=your_username
--env JENKINS_API_TOKEN=your_token

OAuth Support

This server forwards any Authorization header to Jenkins. If your Jenkins uses OAuth (via plugins), just pass the OAuth token as JENKINS_BEARER_TOKEN.

🐛 Troubleshooting

Server Not Showing in Claude

✅ Check path is absolute
✅ Run npm install && npm run build
✅ Verify environment variables
✅ Restart Claude completely

Authentication Errors

# Test your credentials
curl -u username:token https://your-jenkins.com/api/json

If this returns JSON, your credentials are valid!

Build Errors

# Clean rebuild
npm run clean && npm run build

Check Logs

Claude Desktop logs:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\mcp*.log

Claude Code CLI logs:

claude mcp get jenkins

🔒 Security Best Practices

✅ Use environment variables (never hardcode tokens)
✅ Use bearer tokens over basic auth when possible
✅ Rotate tokens regularly
✅ Use restricted tokens (limit permissions in Jenkins)
✅ Never commit tokens to version control
✅ Protect config files (claude_desktop_config.json)

📊 Tech Stack

Runtime: Node.js 20+
Language: TypeScript 5.3+
Target: ES2023
Protocol: MCP 1.0 (stdio transport)
HTTP Client: Native Fetch API
Module System: ESM

🤝 Contributing

Contributions welcome! Please ensure:

TypeScript strict mode compliance
All tools properly typed
Build passes: npm run build
Tools registered in both tools array and toolHandlers

📄 License

MIT License - see LICENSE file

🙏 Acknowledgments

Built with Model Context Protocol
Jenkins REST API by Jenkins Project

📮 Support

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions

Made with ❤️ for the DevOps & AI community

⭐ Star this repo if it helped you!