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