Rundeck MCP Setup

Rundeck MCP — Local Setup Skill

Purpose: Get the Rundeck MCP server built and wired into Claude Code over stdio.

When to use:

• After cloning the repo for the first time
• When the server is not registered, or claude mcp list shows rundeck-mcp as disconnected

When NOT to use:

• If the server is already registered and connected (claude mcp list shows rundeck-mcp as connected)

What This Skill Does

1. Checks Node.js is available
2. Installs npm dependencies (if needed)
3. Builds TypeScript → dist/
4. Prompts for Rundeck credentials
5. Creates .mcp.json in the repo root with a stdio entry (command/args/env)
6. Adds rundeck-mcp to enabledMcpjsonServers in ~/.claude/settings.json

Execution Steps

IMPORTANT: Follow these steps in order. Do NOT skip steps.

Before Starting: Create Task List

Create all tasks upfront so the user can track progress. Use TaskCreate for each — store the real IDs returned:

TaskCreate "Verify environment"
TaskCreate "Install dependencies"
TaskCreate "Build project"
TaskCreate "Collect credentials"
TaskCreate "Configure .mcp.json"
TaskCreate "Register in ~/.claude/settings.json"

Step 1: Verify Working Directory

TaskUpdate taskId=<verify_env_id> status="in_progress"

Locate the repo root via git — this works regardless of which directory the shell is currently in:

git rev-parse --show-toplevel 2>/dev/null

Store the result as REPO. If the command fails, stop:

"Not inside a git repository. Clone rundeck_mcp and try again."

Confirm it is the correct repo:

ls $REPO/package.json $REPO/src/index.ts 2>/dev/null

If any file is missing, stop:

"This does not appear to be the rundeck_mcp repository."

Change into the repo root so all subsequent relative paths work correctly:

cd "$REPO"

Check Node.js:

node --version && npm --version

If Node.js is not found, stop:

"Node.js is required. Please install Node.js 24+ from https://nodejs.org and try again."

TaskUpdate taskId=<verify_env_id> status="completed"

Step 2: Install Dependencies (if needed)

TaskUpdate taskId=<install_deps_id> status="in_progress"

test -d node_modules && echo "exists" || echo "missing"

If missing:

npm install

If npm install fails, report the error and stop.

TaskUpdate taskId=<install_deps_id> status="completed"

Step 3: Build the Project (if needed)

TaskUpdate taskId=<build_id> status="in_progress"

test -f dist/index.js && echo "built" || echo "needs build"

If dist/index.js does not exist:

npm run build

If the build fails, show the error output and stop.

TaskUpdate taskId=<build_id> status="completed"

Step 4: Collect Credentials

TaskUpdate taskId=<credentials_id> status="in_progress"

Ask the user for their Rundeck instance URL and API token (generated from their Rundeck user profile). Never echo the token back or log it.

TaskUpdate taskId=<credentials_id> status="completed"

Step 5: Configure .mcp.json

TaskUpdate taskId=<mcp_json_id> status="in_progress"

test -f .mcp.json && echo "exists" || echo "missing"

If missing, create it (use Write), filling in the absolute path to dist/index.js and the credentials collected in Step 4:

{
  "mcpServers": {
    "rundeck-mcp": {
      "command": "node",
      "args": ["<REPO>/dist/index.js"],
      "env": {
        "RUNDECK_URL": "<RUNDECK_URL>",
        "RUNDECK_TOKEN": "<RUNDECK_TOKEN>",
        "RUNDECK_API_VERSION": "46"
      }
    }
  }
}

If exists, check if the entry is present:

grep -q "rundeck-mcp" .mcp.json && echo "present" || echo "missing"

If missing, use Edit to add the "rundeck-mcp" entry above inside mcpServers. If present, use Edit to update its env values with the credentials from Step 4.

TaskUpdate taskId=<mcp_json_id> status="completed"

Step 6: Register in ~/.claude/settings.json

TaskUpdate taskId=<settings_id> status="in_progress"

grep -q "rundeck-mcp" ~/.claude/settings.json && echo "enabled" || echo "not enabled"

If not present, Read the file then use Edit to add "rundeck-mcp" to the enabledMcpjsonServers array. If the array doesn't exist yet, add it.

TaskUpdate taskId=<settings_id> status="completed"

Final Report

Rundeck MCP server is configured.

  Rundeck:  <RUNDECK_URL>
  Config:   .mcp.json  →  "rundeck-mcp"
  Settings: ~/.claude/settings.json  →  enabledMcpjsonServers

Reload Claude Code (or restart your session) to connect.

To rebuild after source changes:  /rundeck-mcp-rebuild

Error Reference