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]

| Option | Description | Default | | ---------------------------------------------------------------- | ----------------------------------------------------- | --------- | | --jenkins-url | Jenkins server URL | — | | --jenkins-username | Jenkins username | — | | --jenkins-password | Jenkins password or API token | — | | --jenkins-timeout | API request timeout in seconds | 5 | | --jenkins-verify-ssl / --no-jenkins-verify-ssl | Verify SSL certificates | true | | --jenkins-session-singleton / --no-jenkins-session-singleton | Reuse Jenkins client within session | true | | --read-only | Only register read-only tools | false | | --allow-full-console-output | Register the unsafe raw full-console-output tool | false | | --transport | Transport mode: stdio | sse | streamable-http | stdio | | --host | Host for HTTP transports | 0.0.0.0 | | --port | Port for HTTP transports | 9887 |

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.

| Header | Description | | -------------------- | ----------------------------- | | x-jenkins-url | Jenkins server URL | | x-jenkins-username | Jenkins username | | x-jenkins-password | Jenkins password or API token |

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

Available Tools

Job / Item Tools

| Tool | Description | Parameters | Read-Only | | ----------------- | ----------------------------------------- | ------------------------------------------------------- | --------- | | get_all_items | Get all jobs and folders from Jenkins | — | Yes | | get_item | Get a specific job or folder by full name | fullname | Yes | | get_item_config | Get job configuration XML | fullname | Yes | | set_item_config | Update job configuration XML | fullname, config_xml | No | | query_items | Search items with regex filters | class_pattern?, fullname_pattern?, color_pattern? | Yes | | build_item | Trigger a job build | fullname, build_type, params? | No |

Build Tools

| Tool | Description | Parameters | Read-Only | | --------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------- | --------- | | get_build | Get build details | fullname, number? | Yes | | get_build_console_tail | Get the recent tail of build console output | fullname, number?, max_bytes? | Yes | | get_build_console_chunk | Read incremental console output by offset | fullname, start, number?, max_bytes? | Yes | | search_build_console | Search console output incrementally with excerpts | fullname, query, number?, max_bytes?, ... | Yes | | get_build_failure_excerpt | Get focused failure excerpts and test hints via incremental scan | fullname, number?, max_bytes?, max_excerpts? | Yes | | get_build_console_output | Get raw full console log output | fullname, number? | Yes | | get_build_test_report | Get test results report | fullname, number? | Yes | | get_build_scripts | Extract build scripts (for replay) | fullname, number? | Yes | | get_running_builds | Get all currently running builds | — | Yes | | stop_build | Stop a running build | fullname, number | No |

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

| Tool | Description | Parameters | Read-Only | | ----------------- | -------------------------------------- | -------------------- | --------- | | get_all_nodes | Get all compute nodes | — | Yes | | get_node | Get a specific node with executor info | name | Yes | | get_node_config | Get node configuration XML | name | Yes | | set_node_config | Update node configuration XML | name, config_xml | No |

Queue Tools

| Tool | Description | Parameters | Read-Only | | --------------------- | ---------------------------------- | ---------- | --------- | | get_all_queue_items | Get all items waiting in the queue | — | Yes | | get_queue_item | Get a specific queue item by ID | id | Yes | | cancel_queue_item | Cancel a queued item | id | No |

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

| Command | Description | | -------------------- | ---------------------------------------------------- | | pnpm dev | Start in watch mode (auto-reload on changes) | | pnpm build | Build production bundle with tsup | | pnpm test | Run tests with Vitest | | pnpm test:watch | Run tests in watch mode | | pnpm test:coverage | Run tests with coverage report | | pnpm check | Run all checks: format, lint, typecheck, test, build | | pnpm lint | Run ESLint | | pnpm format | Format code with Prettier | | pnpm commit | Interactive conventional commit with Commitizen | | pnpm changeset | Create a changeset for release |

License

MIT