jenkins-mcp

A Model Context Protocol (MCP) server that provides AI assistants with full access to Jenkins CI/CD systems. Built with TypeScript and Node.js, it enables Claude, Cursor, and other MCP-compatible clients to query, manage, and control Jenkins jobs, builds, nodes, and queues through natural language.

Table of Contents

• Features

• Usage

• Configuration

• MCP Client Integration

• Available Tools

• Transport Modes

• Architecture

• Development

Features

• 23 MCP Tools — Full Jenkins automation: jobs, builds, nodes, and queues

• 3 Transport Modes — stdio, sse, and streamable-http for different deployment scenarios

• Read-Only Mode — Restrict to safe, read-only operations for controlled environments

• Per-Request Auth — HTTP header-based Jenkins auth for multi-user/multi-tenant setups

• SSL Configuration — Toggle SSL certificate verification for self-signed certs

• Session Singleton — Reuse Jenkins client connections within a session for efficiency

• CSRF Protection — Automatic crumb/token handling for Jenkins security

• Folder Support — Full support for nested Jenkins folders and multi-branch pipelines

• TypeScript Strict Mode — Fully typed codebase with strict compiler checks

Usage

MCP Client

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "jenkins-mcp",
        "--jenkins-url",
        "https://jenkins.example.com",
        "--jenkins-username",
        "your-username",
        "--jenkins-password",
        "your-api-token"
      ]
    }
  }
}

Claude Code

claude mcp add jenkins -- npx jenkins-mcp \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username your-username \
  --jenkins-password your-api-token

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "jenkins-mcp",
        "--jenkins-url",
        "https://jenkins.example.com",
        "--jenkins-username",
        "your-username",
        "--jenkins-password",
        "your-api-token"
      ]
    }
  }
}

Read-Only Mode

For safety in production environments, use --read-only to disable all write operations:

{
  "mcpServers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "jenkins-mcp",
        "--read-only",
        "--jenkins-url",
        "https://jenkins.example.com",
        "--jenkins-username",
        "your-username",
        "--jenkins-password",
        "your-api-token"
      ]
    }
  }
}

Configuration

Jenkins-MCP can be configured through CLI arguments, environment variables, or HTTP headers (for HTTP transports).

CLI Options

jenkins-mcp [options]

Environment Variables

Jenkins-MCP reads configuration from process environment variables. It does not auto-load .env files by itself.

If you use a local .env file, load it before starting the server (for example: set -a; source .env; set +a), then run jenkins-mcp.

Example .env values:

# Jenkins server URL
jenkins_url=https://jenkins.example.com/

# Jenkins basic auth
jenkins_username=your-username
jenkins_password=your-api-token

# Optional runtime settings
jenkins_timeout=5
jenkins_verify_ssl=true
jenkins_session_singleton=true

HTTP Headers (HTTP Transports Only)

When using sse or streamable-http transport, Jenkins credentials can be provided per-request via HTTP headers. This enables multi-user scenarios where different requests authenticate against different Jenkins instances.

Each provided header overrides the corresponding environment variable for that request. Missing header values fall back to environment configuration.

Available Tools

Job / Item Tools

Build Tools

For large logs, prefer get_build_console_tail -> search_build_console -> get_build_console_chunk. get_build_console_output is disabled by default and only registered when --allow-full-console-output is set. Large-log helper tools enforce server-side byte ceilings even if the caller asks for more, and search-style tools scan logs incrementally instead of fetching consoleText.

Recommended Troubleshooting Flow

For a failed build, prefer this sequence:

1. get_build to confirm result, building, and the target build number.

2. get_build_failure_excerpt to get focused failure snippets plus failing test hints.

3. search_build_console with anchors such as Caused by:, ERROR, FAILED, or a failing test name.

4. get_build_console_chunk to continue reading from a returned nextStart offset when the first excerpt is not enough.

5. get_build_console_output only when raw full log export is explicitly needed.

For a running build, prefer this sequence:

1. get_build to confirm the build is still running.

2. get_build_console_tail to inspect the latest output window.

3. search_build_console for known error anchors in the recent window.

4. get_build_console_chunk with the last nextStart value to keep polling without rereading old output.

Node Tools

Queue Tools

Tools marked Read-Only: No are only available when --read-only is not set.

Transport Modes

stdio (Default)

Standard input/output transport for direct MCP client integration. This is the recommended mode for Claude Desktop, Cursor, and other desktop MCP clients.

jenkins-mcp --transport stdio \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username user --jenkins-password token

SSE (Server-Sent Events)

HTTP-based transport using Server-Sent Events. Suitable for web-based clients or remote access scenarios.

jenkins-mcp --transport sse \
  --host 127.0.0.1 --port 9887 \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username user --jenkins-password token

• SSE endpoint: GET /sse — establishes an SSE connection and returns a session

• Message endpoint: POST /message?sessionId=<id> — sends messages to the session

Streamable HTTP

Session-based HTTP MCP transport over /mcp. Sessions are initialized via MCP initialize, then correlated with mcp-session-id in follow-up requests.

jenkins-mcp --transport streamable-http \
  --host 127.0.0.1 --port 9887 \
  --jenkins-url https://jenkins.example.com \
  --jenkins-username user --jenkins-password token

• MCP endpoint: POST /mcp — handles all MCP protocol messages

Architecture

┌─────────────────────────────────────────────────┐
│                  MCP Client                     │
│          (Claude, Cursor, etc.)                 │
└──────────────────┬──────────────────────────────┘
                   │  MCP Protocol
┌──────────────────▼──────────────────────────────┐
│              Transport Layer                    │
│      stdio │ SSE │ Streamable HTTP              │
├──────────────────┬──────────────────────────────┤
│           MCP Server (mcp.ts)                   │
│     Tool registration & error handling          │
├──────────────────┬──────────────────────────────┤
│          Tool Handlers                          │
│   item.ts │ build.ts │ node.ts │ queue.ts       │
├──────────────────┬──────────────────────────────┤
│         Jenkins REST Client                     │
│    HTTP requests, auth, CSRF, timeout           │
├──────────────────┬──────────────────────────────┤
│           Jenkins Server                        │
│         (REST API endpoint)                     │
└─────────────────────────────────────────────────┘

Key design patterns:

• Dependency Injection — ToolRuntime interface enables testable tool handlers

• Session Management — HTTP transports map sessions to isolated runtime contexts

• Per-Request Auth — HTTP headers override environment config for multi-tenant use

• Automatic CSRF — Crumb tokens are fetched and cached transparently

Development

Scripts

License

MIT