What Rundeck does, in brief

Rundeck (and Runbook Automation, its SaaS counterpart) is a runbook automation and orchestration platform: it turns operational scripts and procedures into definable, schedulable, access-controlled jobs that can run across your infrastructure — on servers, containers, or through Runners in environments you don’t want to expose directly.
The use cases that show up most often:

• Job automation — turning a manual runbook or one-off script into a reusable, scheduled, auditable job; jobs aren’t limited to scripts either — plugins package pre-built steps and integrations with other tools (Jira, HTTP calls, SQL execution, Ansible, Kubernetes, Docker, ServiceNow, and more) so a job can drive other systems, not just the shell
• Self-service operations — letting teams trigger approved actions themselves, without opening a ticket or asking ops to run something by hand
• Node and inventory management — discovering and organizing the servers, containers, or runners a job can target, via resource model sources
• Access control — scoping exactly who can see, edit, or run what, via ACL policies, so self-service doesn’t mean unrestricted
• Distributed execution at scale — via Runners, reaching infrastructure that isn’t directly reachable from the Rundeck server itself

None of this is new — it’s the reason people run Rundeck in the first place. What’s new is how much faster you can get to any of it.

From answers to action: where AI meets Rundeck

Ask an AI assistant a Rundeck question — “how do I write a node filter that excludes staging?” — and it’ll probably give you a solid answer. Ask it to do something — “create this job,” “check why this execution failed,” “spin up a runner” — and it hits a wall. It can describe the curl command. It can’t run it. It doesn’t have credentials, it doesn’t know your instance, and it has no safe way to act even if it did.

That gap is what the Model Context Protocol (MCP) closes. The Rundeck MCP server gives any MCP-compatible assistant — Claude Desktop, Claude Code, Cursor, VS Code — direct, authenticated access to your real Rundeck or Runbook Automation instance. Ask it to look something up, run a job, or generate one from scratch, and it does the real thing against your real instance, instead of handing you a command to run yourself.

Under the hood, it gives the assistant three things: Rundeck’s own documentation (so answers come from the real docs, not a guess), live API access (projects, jobs, executions, nodes, runners, ACL policies), and structured generation and validation for job definitions and ACL policies, so what gets created is checked for structural mistakes before it’s ever imported or applied — Rundeck itself is still the final word on whether it’s accepted.

Where it fits into the use cases above

Each of the use cases above is something Rundeck already exposes through its API, so none of them depends on the UI. The MCP server puts an assistant directly on that surface. It reads the real documentation, knows the permission model, and acts on your instance with your token. That changes who can do the work and how quickly. Concretely, the MCP server can:

• Answer Rundeck questions on the spot, pulled from the official docs. “How do I write a node filter that excludes staging?” — a real answer, not a guess.

• Query and drive a real instance — projects, jobs, executions, nodes, runs. “Show me the last 5 failed executions for this job, and why they failed.” — operational visibility without digging through the UI one execution at a time.

• Generate and validate job definitions from a plain-language description. “Create a job that reports disk space and running processes, and run it locally.” — job automation, from a sentence to a validated, running job.

• Validate and manage ACL policies, catching structural mistakes before submission. “Create an ACL policy so this group can run jobs and view nodes in this project, but nothing else.” — access control, checked before it’s applied, not after.

• Provision Runners on Docker, Kubernetes, Linux, or Windows. “Provision a Runner for this environment and give me a way to start it.” — distributed execution, without hand-assembling the registration steps.

The assistant isn’t replacing Rundeck’s model — it’s replacing the friction of getting into it.

The benefits this actually adds up to

• Automations start faster. Going from “we should automate this” to a working, scheduled job stops requiring a block of time clicking through the job GUI, or writing and applying Terraform — it’s now a conversation.

• Complex areas move faster too, not just the easy ones. ACL policies are exactly the kind of thing that’s easy to get subtly wrong by hand — a rule with no by section applies to no one, a typo’d action name silently fails for that resource type, and Rundeck won’t tell you why access just isn’t working. The validator catches that class of structural mistake before anything is applied. Separately, because the assistant already knows Rundeck’s permission model, it also knows a project-scoped grant needs a companion system-scope policy before that project even shows up in someone’s list — the kind of gap no local validator checks for, but an assistant that understands the model can flag.

• Lower ongoing maintenance overhead. Bulk changes — rescheduling a whole group of jobs, adjusting a shared script across many jobs — become one instruction instead of clicking into each job individually.

• A shorter learning curve for new users. Someone new to Rundeck doesn’t need to already know ACL syntax or node filter semantics to get something real done — they can ask, see the result, and learn the underlying model as they go instead of before they start.

• Easier inventory upkeep. Resource model sources and node definitions can be described and adjusted in plain language instead of hand-maintained files.

Safe to act: guardrails and traceability:

Giving an assistant the ability to act on a real instance is only useful if it’s also safe:

1. Your client’s approval is an extra layer you control. Most MCP clients ask for approval before each tool call, and that behavior belongs to the client, not to the Rundeck MCP server. We recommend keeping it on for anything that writes to a production instance: creating a job, running one, or changing an ACL policy.

2. The highest-risk actions need a live answer from you. Deleting a resource (any DELETE request), regenerating a runner’s credentials, and updating or deleting an ACL policy can’t be undone, so the server never runs them on the assistant’s say-so. When the assistant requests one, the server pauses the call and uses MCP elicitation to ask your client to show you a confirmation prompt. Only your explicit “accept” lets the request reach Rundeck.
   • The assistant can’t approve it. It never sees or answers the prompt, and no tool parameter can stand in for your answer.
   • It still applies when tool calls are auto-approved. Elicitation is a separate request, made while the tool runs, from your client’s per-call approval.
   • No prompt, no action. If you decline, or your client doesn’t support elicitation, the request is blocked and nothing reaches Rundeck.

3. You control the blast radius with a scoped token. The assistant only has whatever access the API token and ACL policy behind it grants — read-only if that’s all you give it, or scoped to a single project. The MCP server doesn’t create new permissions; it uses the ones you’ve already decided to grant.

The toolkit

That server exposes a small set of purpose-built tools:

• Docs search — answers pulled from Rundeck’s own documentation, not a guess.

• Instance access — the generic bridge to your real Rundeck instance: projects, jobs, executions, nodes, and more, plus triggering a job run.
• Job authoring — generates a job definition from a plain-language description and checks it for structural mistakes before it’s ever imported (Rundeck itself remains the final check).
• ACL management — writes and validates access policies, catching structural mistakes up front; updating or deleting an existing policy requires explicit confirmation before it’s applied.
• Runner provisioning — registers a Runner (Docker, Kubernetes, Linux, or Windows) in Rundeck and hands you what you need to start it — you still install and run it in your own environment.
• Resource model management — configures and edits the node/inventory sources a project uses.

• Instance switching — if you’ve registered more than one Rundeck instance (see below), a dedicated tool lets you say “switch to staging” mid-conversation instead of restarting with different credentials.

Installing it

The server ships in two ways, and both work with any MCP client — Claude Code, Claude Desktop, Cursor, VS Code. Point either one at your Rundeck URL and API token, and you’re connected.

Docker (recommended — no Node.js to manage):

claude mcp add rundeck-mcp -- docker run -i --rm \
  -e RUNDECK_URL=https://your-rundeck-instance.example.com \
  -e RUNDECK_TOKEN=your-rundeck-api-token-here \
  rundeck/mcp:latest

npx (no Docker required):

claude mcp add rundeck-mcp \
  -e RUNDECK_URL=https://your-rundeck-instance.example.com \
  -e RUNDECK_TOKEN=your-rundeck-api-token-here \
  -e RUNDECK_DOCS_PATH=/path/to/rundeck/docs \
  -- npx -y @rundeck/mcp

RUNDECK_DOCS_PATH matters here in a way it doesn’t for Docker: npm install downloads Rundeck’s docs automatically, but into the installed package’s own directory — not wherever your client happens to run it from. Skip this variable and doc-backed answers quietly come back empty instead of erroring.

Both examples use Claude Code’s CLI; the same two options — a Docker image or an npm package — plug into Claude Desktop, Cursor, and VS Code just as directly.
This works the same way whether you have one Rundeck instance or several. The examples above point at a single RUNDECK_URL/RUNDECK_TOKEN pair, which is all most setups need. If you work across multiple instances — say, staging and production, or several customer environments — you can instead register them all at once and ask the assistant to “switch to staging” mid-conversation, without restarting or re-authenticating (that’s the instance-switching tool mentioned above).

Full install instructions for every client, plus environment variables, multi-instance setup, and best practices for scoping tokens, are in the docs: docs.rundeck.com/docs/mcp.

What this looks like in practice

Here’s the first example above, end to end — illustrative, but following the exact call sequence the server actually makes, tool by tool:

> Create a job in "ops-demo" called "Check disk and processes" that runs a bash
  script reporting disk space and running processes, then create and run it.

⏺ I'll generate the job definition, validate it, import it, and run it.

⏺ mcp__rundeck__job_create(name: "Check disk and processes", project: "ops-demo",
    workflow_steps: [{ type: "script", script: "#!/bin/bash\ndf -h\nps aux" }])
  ⎿ returns a YAML job definition (not yet created in Rundeck)

⏺ mcp__rundeck__job_validate(job_definition: "<the YAML above>", format: "yaml")
  ⎿ { "valid": true, "errors": [], "warnings": [] }

⏺ mcp__rundeck__api_call(method: "POST", endpoint: "project/ops-demo/jobs/import",
    content_type: "application/yaml", body: "<the YAML above>")
  ⎿ 200 OK — job imported, id 3b8a86d5-4fc3-4e21-9e77-1a2f6c9d1234

⏺ mcp__rundeck__api_call(method: "POST", endpoint: "job/3b8a86d5-4fc3-4e21-9e77-1a2f6c9d1234/run")
  ⎿ 200 OK — execution #482 started

⏺ mcp__rundeck__api_call(method: "GET", endpoint: "execution/482/output")
  ⎿ 200 OK — execution finished successfully

Output:

  Filesystem      Size  Used Avail Use% Mounted on
  /dev/sda1        40G   12G   28G  30% /

  USER     PID  %CPU  %MEM  COMMAND
  root       1   0.0   0.1  /sbin/init
  rundeck  482   0.2   0.4  java
  ...

Two things worth noticing: the job gets validated before it’s imported — a malformed step or bad schedule fails here, not after a broken import in the UI — and creating the definition (job_create) is a separate, non-destructive step from actually importing and running it, so nothing touches your instance until you say run it. The same validate-then-apply pattern is what catches structural ACL mistakes before a policy is ever applied — see “The benefits” above.

Try it

Start with a question you’d normally ask in a docs search or a teammate’s DM, then work up to generating a job. Setup takes a few minutes either way — Docker or npm — and the full walkthrough is at docs.rundeck.com/docs/mcp.

The server itself is open source: the code is on GitHub at github.com/rundeck/mcp, the image is on Docker Hub at hub.docker.com/r/rundeck/mcp, and the package is on npm as @rundeck/mcp. Issues, feedback, and contributions are welcome.