Jenkins

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

🌟 Features

• 🔐 Flexible Authentication - Bearer tokens, Basic auth, OAuth support
• ⚙️ Flexible Configuration - CLI args or MCP_JENKINS_* env vars (priority-based)
• 🔒 Tool Filtering - Allowlist or blocklist tools via MCP_JENKINS_ALLOW_TOOLS / MCP_JENKINS_BLOCK_TOOLS
• 🔀 Multi-Instance Support - Connect to multiple Jenkins servers in one MCP entry, select per tool call
• 🛠️ 37 Tools - Comprehensive 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/kud/mcp-jenkins.git
cd mcp-jenkins
npm install
npm run build

Configuration Priority

The server supports 2 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.

Quick Setup Example (Claude CLI)

Using environment variables (recommended):

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

Using CLI arguments (override env vars):

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

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 \
  --env MCP_JENKINS_URL=https://pipeline.yourcompany.com \
  --env MCP_JENKINS_USER=your_username \
  --env MCP_JENKINS_API_TOKEN=your_api_token \
  -- npx --yes @kud/mcp-jenkins@latest

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 \
  -- node $HOME/path/to/mcp-jenkins/dist/index.js \
  --url https://pipeline.yourcompany.com \
  --user your_username \
  --api-token your_api_token

claude mcp add --transport stdio --scope user jenkins \
  --env MCP_JENKINS_URL="https://pipeline.yourcompany.com,https://scheduler.yourcompany.com" \
  --env MCP_JENKINS_USER="your_username,your_username" \
  --env MCP_JENKINS_API_TOKEN="token1,token2" \
  -- npx --yes @kud/mcp-jenkins@latest
# Instances named "pipeline" and "scheduler" automatically from hostnames

🌐 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"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com",
        "MCP_JENKINS_USER": "your_username",
        "MCP_JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

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

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com,https://scheduler.yourcompany.com",
        "MCP_JENKINS_USER": "your_username,your_username",
        "MCP_JENKINS_API_TOKEN": "token1,token2"
      }
    }
  }
}

📝 VSCode

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

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

{
  "cline.mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["@kud/mcp-jenkins"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com,https://scheduler.yourcompany.com",
        "MCP_JENKINS_USER": "your_username,your_username",
        "MCP_JENKINS_API_TOKEN": "token1,token2"
      }
    }
  }
}

🌐 Cursor

For: Cursor IDE with built-in AI

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

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com,https://scheduler.yourcompany.com",
        "MCP_JENKINS_USER": "your_username,your_username",
        "MCP_JENKINS_API_TOKEN": "token1,token2"
      }
    }
  }
}

🌊 Windsurf

For: Windsurf AI-powered code editor

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

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com,https://scheduler.yourcompany.com",
        "MCP_JENKINS_USER": "your_username,your_username",
        "MCP_JENKINS_API_TOKEN": "token1,token2"
      }
    }
  }
}

🤖 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"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com",
        "MCP_JENKINS_USER": "your_username",
        "MCP_JENKINS_API_TOKEN": "your_api_token"
      }
    }
  }
}

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "--yes",
        "@kud/mcp-jenkins@latest",
        "--url",
        "https://pipeline.yourcompany.com",
        "--user",
        "your_username",
        "--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", "..."]

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": ["--yes", "@kud/mcp-jenkins@latest"],
      "env": {
        "MCP_JENKINS_URL": "https://pipeline.yourcompany.com,https://scheduler.yourcompany.com",
        "MCP_JENKINS_USER": "your_username,your_username",
        "MCP_JENKINS_API_TOKEN": "token1,token2"
      }
    }
  }
}

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

MCP_JENKINS_URL=https://pipeline.yourcompany.com,https://scheduler.yourcompany.com
MCP_JENKINS_USER=your_username,your_username
MCP_JENKINS_API_TOKEN=token1,token2

🛠️ Available Tools

📋 Job Operations (11 tools)

🔨 Build Operations (9 tools)

🧪 Testing & Artifacts (3 tools)

📊 Queue Management (2 tools)

🖥️ System & Nodes (8 tools)

🗂️ Views (2 tools)

🔀 Instances & Admin (2 tools)

Total: 37 Tools covering ~95% 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 MCP_JENKINS_URL=https://pipeline.yourcompany.com
export MCP_JENKINS_USER=your_username
export MCP_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 2-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

   • MCP_JENKINS_URL
   • MCP_JENKINS_USER
   • MCP_JENKINS_API_TOKEN
   • MCP_JENKINS_BEARER_TOKEN

Multiple Instances

Connect to more than one Jenkins server in a single MCP entry using comma or pipe-separated values.

Automatic naming (derived from URL hostname):

export MCP_JENKINS_URL="https://pipeline.yourcompany.com,https://scheduler.yourcompany.com"
export MCP_JENKINS_USER="your_username,your_username"
export MCP_JENKINS_API_TOKEN="token1,token2"
# Instances are automatically named "pipeline" and "scheduler"

Custom naming with MCP_JENKINS_INSTANCES:

Use MCP_JENKINS_INSTANCES when you want explicit names (e.g., the hostname isn't descriptive enough, or both instances share the same host):

export MCP_JENKINS_INSTANCES="ci,prod"
export MCP_JENKINS_URL="https://jenkins.yourcompany.com/ci,https://jenkins.yourcompany.com/prod"
export MCP_JENKINS_USER="your_username,your_username"
export MCP_JENKINS_API_TOKEN="token1,token2"
# Instances are named "ci" and "prod"

The number of values in MCP_JENKINS_INSTANCES must match the number of URLs.

Then pass instance in tool calls:

"Trigger a build for 'deploy' on the scheduler instance"
"List jobs on ci"

The first instance is always the default — tools work without instance if you only have one server.

Note: Use | as delimiter instead of , if any value might contain a comma (e.g., unusual URLs).

Tool Filtering

Control which tools are exposed to the AI using an allowlist or blocklist.

Allowlist — expose only specific tools:

export MCP_JENKINS_ALLOW_TOOLS="jenkins_list_jobs,jenkins_get_job_status,jenkins_get_build_status"

Blocklist — hide specific tools (all others remain available):

export MCP_JENKINS_BLOCK_TOOLS="jenkins_delete_job,jenkins_trigger_build,jenkins_safe_restart"

If both are set, MCP_JENKINS_ALLOW_TOOLS takes precedence.

Read-only monitoring preset — block all write/destructive tools:

export MCP_JENKINS_BLOCK_TOOLS="jenkins_trigger_build,jenkins_stop_build,jenkins_delete_build,jenkins_cancel_queue,jenkins_enable_job,jenkins_disable_job,jenkins_delete_job,jenkins_create_job,jenkins_update_job_config,jenkins_rename_job,jenkins_copy_job,jenkins_toggle_node_offline,jenkins_quiet_down,jenkins_cancel_quiet_down,jenkins_safe_restart,jenkins_replay_build"

Examples

All CLI args:

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

Mixed (CLI overrides env):

MCP_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

🔐 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 MCP_JENKINS_BEARER_TOKEN
• For Basic auth: Use it as MCP_JENKINS_API_TOKEN (along with MCP_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 MCP_JENKINS_BEARER_TOKEN=your_token

Basic Auth:

--env MCP_JENKINS_USER=your_username
--env MCP_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 MCP_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 LICENSE file

🙏 Acknowledgments

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

📮 Support

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