kud/mcp-jenkins

Jenkins MCP Server

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

🌟 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):

1. CLI arguments - --url, --user, --api-token, --bearer-token
2. MCP_JENKINS_* environment variables - MCP_JENKINS_URL, MCP_JENKINS_USER, etc.
3. 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

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

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

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

🌐 Claude Code Web

For: Claude.ai in your browser

🖥️ Claude Desktop

For: Claude AI desktop application

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

notepad %APPDATA%\Claude\claude_desktop_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"
      ]
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      ]
    }
  }
}

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

📝 VSCode

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

{
  "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"
      }
    }
  }
}

🌐 Cursor

For: Cursor IDE with built-in AI

{
  "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"
      }
    }
  }
}

🌊 Windsurf

For: Windsurf AI-powered code editor

{
  "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"
      }
    }
  }
}

🤖 GitHub Copilot

For: GitHub Copilot in VSCode or other editors

💻 GitHub Copilot CLI

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

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

{
  "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"
      }
    }
  }
}

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"
      ]
    }
  }
}'

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

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

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

🛠️ Available Tools

📋 Job Operations (5 tools)

🔨 Build Operations (9 tools)

🧪 Testing & Artifacts (3 tools)

📊 Queue Management (2 tools)

🖥️ System Information (5 tools)

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

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

1. 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' };
};

2. Add method to JenkinsClient (src/lib/jenkins-client.ts)

3. Register in src/index.ts:

   • Import the tool
   • Add to tools array
   • Add to toolHandlers map

4. Rebuild:

npm run build

⚙️ Configuration

Priority System

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

1. 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

2. MCP_JENKINS_ Environment Variables* (Medium Priority)

   • MCP_JENKINS_URL
   • MCP_JENKINS_USER
   • MCP_JENKINS_API_TOKEN
   • MCP_JENKINS_BEARER_TOKEN

3. 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

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

Step 2: Create API Token

1. Scroll to the API Token section
2. Under "Current token(s)", click the Add new token button
3. Enter a descriptive name (e.g., "Jenkins MCP" or "AI Assistant")
4. Click Generate
5. ⚠️ 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

1. ✅ Check path is absolute
2. ✅ Run npm install && npm run build
3. ✅ Verify environment variables
4. ✅ 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:

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

📄 License

MIT License - see file

🙏 Acknowledgments

• Built with Model Context Protocol
• Jenkins REST API by Jenkins Project

📮 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions