Rundeck MCP Server

Rundeck MCP Server

This is a fork of the official Rundeck MCP server, adapted and pinned for Rundeck 4.17.6 Community (API v45). It ships the matching documentation snapshot and sensible defaults for that version, so it works out of the box against a 4.17.6 Community instance.

Give any MCP-compatible AI assistant (Claude Desktop, Claude Code, Cursor, VS Code, and others) direct, authenticated access to your Rundeck instance. Point it at your Rundeck URL and API token, and your assistant can:

• Answer Rundeck questions on the spot — API usage, job schemas, node filters, plugin configuration, and more, pulled straight from the official docs.

• Query and drive your real Rundeck instance — look up projects, jobs, executions, and nodes, or trigger a job run, without leaving the chat.

• Generate and validate job definitions — describe a job in plain language and get back a ready-to-import YAML/JSON definition, checked against Rundeck's schema before you deploy it.

This build targets Rundeck 4.17.6 Community (API v45) by default, and ships the matching documentation snapshot (v4.17.5-20240304, the closest published docs tag for the 4.17.x line). Both the API version and docs version are configurable — see Environment variables.

For the full breakdown of resources, tools, and prompts exposed by the server, see TECHNICAL-CAPABILITIES.md.

Quick Start

Requires Node.js 22.19+ (see .nvmrc).

# 1. Install dependencies (also downloads the Rundeck docs via postinstall)
npm install

# 2. Build TypeScript -> dist/
npm run build

# 3. (optional) Run the test suite
npm test

Then point your MCP client at the built server (see below). That's the whole setup — there's no private registry or login step.

Related MCP server: rundeck-mcp-server

Connecting an MCP Client

The server speaks stdio. Point your client at the built dist/index.js with Node, and pass your Rundeck connection via env. Use the absolute path to this repo's dist/index.js.

Most clients (Cursor, Claude Desktop, Kiro, etc.) use an mcpServers JSON block:

{
  "mcpServers": {
    "rundeck-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/rundeck-mcp/dist/index.js"],
      "env": {
        "RUNDECK_URL": "http://127.0.0.1:4440",
        "RUNDECK_TOKEN": "your-rundeck-api-token-here",
        "RUNDECK_API_VERSION": "45",
        "RUNDECK_DOCS_PATH": "/absolute/path/to/rundeck-mcp/docs/docs"
      }
    }
  }
}

For VS Code's mcp.json, which can prompt for secrets instead of hardcoding them:

{
  "mcp": {
    "inputs": [
      { "type": "promptString", "id": "rundeck-url", "description": "Rundeck Instance URL" },
      { "type": "promptString", "id": "rundeck-token", "description": "Rundeck API Token", "password": true }
    ],
    "servers": {
      "rundeck-mcp": {
        "type": "stdio",
        "command": "node",
        "args": ["/absolute/path/to/rundeck-mcp/dist/index.js"],
        "env": {
          "RUNDECK_URL": "${input:rundeck-url}",
          "RUNDECK_TOKEN": "${input:rundeck-token}",
          "RUNDECK_API_VERSION": "45",
          "RUNDECK_DOCS_PATH": "/absolute/path/to/rundeck-mcp/docs/docs"
        }
      }
    }
  }
}

For Claude Code, add it via the CLI:

claude mcp add rundeck-mcp \
  -e RUNDECK_URL=http://127.0.0.1:4440 \
  -e RUNDECK_TOKEN=your-rundeck-api-token-here \
  -e RUNDECK_API_VERSION=45 \
  -e RUNDECK_DOCS_PATH=/absolute/path/to/rundeck-mcp/docs/docs \
  -- node /absolute/path/to/rundeck-mcp/dist/index.js

Why RUNDECK_DOCS_PATH? Docs-backed features (docs_search, the doc resources, and the OpenAPI request validation in api_call) read documentation from disk. npm install downloads it to docs/docs in this repo, but an MCP client launches the server from its own working directory, so set RUNDECK_DOCS_PATH to the absolute docs/docs path to be safe. See SETUP.md.

Running in Docker (optional)

If you'd rather run the server in a container, build the image from this repo — no registry login needed:

docker build -t rundeck-mcp .

Then configure your client to launch it (the container downloads docs on startup, so RUNDECK_DOCS_PATH isn't needed):

{
  "mcpServers": {
    "rundeck-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "RUNDECK_URL=http://host.docker.internal:4440",
        "-e", "RUNDECK_TOKEN=your-rundeck-api-token-here",
        "-e", "RUNDECK_API_VERSION=45",
        "rundeck-mcp"
      ]
    }
  }
}

Reaching a Rundeck on the host from inside the container uses host.docker.internal rather than 127.0.0.1 on most setups.

Switching Between Multiple Rundeck Instances

Everything above covers the common case: one Rundeck instance. If you need to switch between more than one (e.g. prod and staging) in the same session without restarting, see SETUP.md.

Spinning up a local Rundeck to test against

This repo includes a docker-compose.yaml that boots a Rundeck 4.17.6 + MySQL stack on http://127.0.0.1:4440:

docker compose up -d

Generate an API token from the Rundeck UI (User Profile → API Tokens) and use it as RUNDECK_TOKEN.

Safety: Approvals and Destructive Actions

This server acts against a real, live Rundeck instance. Deletes, ACL policy changes, and runner credential revocation require confirmation before reaching Rundeck; auto-approve/"auto mode" MCP clients bypass that safety net, and you assume the risk if you use one. See Destructive Actions and Confirmation in TECHNICAL-CAPABILITIES.md for how it works.

Development

npm install        # install dependencies (+ downloads docs via postinstall)
npm run dev        # run the server with auto-restart on source changes
npm run inspect    # test interactively with the MCP Inspector GUI
npm test           # run the test suite
npm run validate   # full check: build + tests + MCP validation scripts
npm run build      # compile TypeScript to dist/

Rebuild (npm run build) after changing anything under src/ — MCP clients run the compiled dist/index.js.

See SETUP.md for environment variables and detailed configuration.

Environment variables