# Rundeck MCP Server
# Rundeck MCP Server

> This is a fork of the [official Rundeck MCP server](https://github.com/rundeck/docs), 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](#environment-variables).

For the full breakdown of resources, tools, and prompts exposed by the server, see [TECHNICAL-CAPABILITIES.md](./TECHNICAL-CAPABILITIES.md).

## Quick Start

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

```bash
# 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.

## 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:

```json
{
  "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:

```json
{
  "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:

```bash
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](./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:

```bash
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):

```json
{
  "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](./SETUP.md#multiple-rundeck-instances-optional).

### 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`:

```bash
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](./TECHNICAL-CAPABILITIES.md#destructive-actions-and-confirmation) in TECHNICAL-CAPABILITIES.md for how it works.

---

## Development

```bash
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](./SETUP.md) for environment variables and detailed configuration.

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `RUNDECK_URL` | — | Rundeck instance URL (required to talk to a live instance) |
| `RUNDECK_TOKEN` | — | API token (required to talk to a live instance) |
| `RUNDECK_API_VERSION` | `45` | API version appended to the base URL (Rundeck 4.17.x) |
| `RUNDECK_DOCS_PATH` | auto-detected | Path to the Rundeck docs directory; set explicitly when launched by an MCP client |
| `RUNDECK_DOCS_TAG` | `v4.17.5-20240304` | `rundeck/docs` tag to download when no docs are present (takes precedence over `RUNDECK_DOCS_BRANCH`) |
| `RUNDECK_DOCS_BRANCH` | — | `rundeck/docs` branch to download instead of a tag; only used when `RUNDECK_DOCS_TAG` is unset |
| `RUNDECK_API_TIMEOUT_MS` | `30000` | Timeout for `api_call`'s underlying HTTP request |
| `RUNDECK_INSTANCES` | — | JSON registry of multiple named instances (enables mid-session switching via `rundeck_connect`) |
| `SKIP_RUNDECK_DOCS_DOWNLOAD` | — | Set to `1` to skip the npm-install-time docs download |
| `RUNDECK_SKIP_OPENAPI_VALIDATE` | — | Set to `1` to skip validating `api_call` params against the shipped OpenAPI spec |