Skip to main content
Glama

Rundeck MCP Server

Rundeck's local MCP (Model Context Protocol) server which provides tools to interact with your Rundeck instance, allowing you to list jobs, run jobs with options, and retrieve execution status and logs directly from your MCP-enabled client.

Prerequisites

  • asdf-vm installed.

  • uv installed globally.

  • A Rundeck API Token. To obtain a Rundeck API Token, follow these steps:

    1. Log in to your Rundeck instance and click on your username in the top-right corner.

    2. Navigate to User Profile and then User API Tokens.

    3. Click Generate New Token, provide a name, and select the appropriate roles.

    4. Copy the generated token and store it securely. You will need this token to configure the MCP server.

    Note: API tokens inherit the permissions of the user who created them. Ensure your user has appropriate access to the jobs you want to manage.

Related MCP server: jenkins-mcp-server

Using with MCP Clients

Cursor Integration

You can configure this MCP server directly within Cursor's settings.json file, by following these steps:

  1. Open Cursor settings (Cursor Settings > Tools > Add MCP, or Cmd+, on Mac, or Ctrl+, on Windows/Linux).

  2. Add the following configuration:

    {
      "mcpServers": {
        "rundeck-mcp": {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "rundeck-mcp",
            "--enable-write-tools"
            // This flag enables write operations on the MCP Server enabling you to run jobs
          ],
          "env": {
            "RUNDECK_API_TOKEN": "${input:rundeck-api-token}",
            "RUNDECK_URL": "http://localhost:4440"
          }
        }
      }
    }

VS Code Integration

You can configure this MCP server directly within Visual Studio Code's settings.json file, allowing VS Code to manage the server lifecycle.

  1. Open VS Code settings (File > Preferences > Settings, or Cmd+, on Mac, or Ctrl+, on Windows/Linux).

  2. Search for "mcp" and ensure "Mcp: Enabled" is checked under Features > Chat.

  3. Click "Edit in settings.json" under "Mcp > Discovery: Servers".

  4. Add the following configuration:

    {
        "mcp": {
            "inputs": [
                {
                    "type": "promptString",
                    "id": "rundeck-api-token",
                    "description": "Rundeck API Token",
                    "password": true
                }
            ],
            "servers": {
                "rundeck-mcp": {
                    "type": "stdio",
                    "command": "uvx",
                    "args": [
                        "rundeck-mcp",
                        "--enable-write-tools"
                        // This flag enables write operations on the MCP Server enabling you to run jobs
                    ],
                    "env": {
                        "RUNDECK_API_TOKEN": "${input:rundeck-api-token}",
                        "RUNDECK_URL": "http://localhost:4440"
                        // Update this to your Rundeck server URL
                    }
                }
            }
        }
    }

Trying it in VS Code Chat (Agent)

  1. Ensure MCP is enabled in VS Code settings (Features > Chat > "Mcp: Enabled").

  2. Configure the server as described above.

  3. Open the Chat view in VS Code (View > Chat).

  4. Make sure Agent mode is selected. In the Chat view, you can enable or disable specific tools by clicking the tools icon.

  5. Enter a command such as List all jobs in project myproject or Run the deploy job with version 1.2.3 to interact with your Rundeck instance through the MCP server.

  6. You can start, stop, and manage your MCP servers using the command palette (Cmd+Shift+P/Ctrl+Shift+P) and searching for MCP: List Servers. Ensure the server is running before sending commands. You can also try to restart the server if you encounter any issues.

Claude Desktop Integration

You can configure this MCP server to work with Claude Desktop by adding it to Claude's configuration file.

  1. Locate your Claude Desktop configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Create or edit the configuration file and add the following configuration:

    {
      "mcpServers": {
        "rundeck-mcp": {
          "command": "uvx",
          "args": [
            "rundeck-mcp",
            "--enable-write-tools"
          ],
          "env": {
            "RUNDECK_API_TOKEN": "your-rundeck-api-token-here",
            "RUNDECK_URL": "http://localhost:4440"
          }
        }
      }
    }
  3. Replace the placeholder values:

    • Replace your-rundeck-api-token-here with your actual Rundeck API Token

    • Replace http://localhost:4440 with your Rundeck server URL

  4. Restart Claude Desktop completely for the changes to take effect.

  5. Test the integration by starting a conversation with Claude and asking something like "List all jobs in project myproject" or "Show me recent executions" to verify the MCP server is working.

    Security Note: Unlike VS Code's secure input prompts, Claude Desktop requires you to store your API token directly in the configuration file. Ensure this file has appropriate permissions (readable only by your user account) and consider the security implications of storing credentials in plain text.

Set up locally

  1. Clone the repository

  2. Install asdf plugins

    asdf plugin add python
    asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
    asdf plugin add uv
  3. Install tool versions using asdf:

    asdf install
  4. Create a virtual environment and install dependencies using uv (now that asdf has set the correct Python and uv versions):

    uv sync
  5. Ensure uv is available globally.

    The MCP server can be run from different places so you need uv to be available globally. To do so, follow the official documentation.

    Tip: You may need to restart your terminal and/or VS Code for the changes to take effect.

  6. Run it locally

    To run your cloned Rundeck MCP Server you need to update your configuration to use uv instead of uvx.

    "rundeck-mcp": {
        "type": "stdio",
        "command": "uv",
        "args": [
            "run",
            "--directory",
            "/path/to/your/mcp-server-directory",
            // Replace with the full path to the directory where you cloned the MCP server, e.g. "/Users/yourname/code/rundeck-mcp",
            "python",
            "-m",
            "rundeck_mcp",
            "--enable-write-tools"
            // This flag enables write operations on the MCP Server enabling you to run jobs
        ],
        "env": {
            "RUNDECK_API_TOKEN": "${input:rundeck-api-token}",
            "RUNDECK_URL": "http://localhost:4440"
            // Update this to your Rundeck server URL
        }
    }

Available Tools and Resources

This section describes the tools provided by the Rundeck MCP server. They are categorized based on whether they only read data or can modify data in your Rundeck instance.

Important: By default, the MCP server only exposes read-only tools. To enable tools that can modify your Rundeck instance (write-mode tools), you must explicitly start the server with the --enable-write-tools flag. This helps prevent accidental job executions.

Tool

Area

Description

Read-only

list_jobs

Jobs

Lists jobs in a project with optional filtering

✅

get_job

Jobs

Retrieves job details including options and defaults

✅

list_executions

Executions

Lists executions with filtering by status or time

✅

get_execution

Executions

Retrieves execution status and details

✅

get_execution_output

Executions

Retrieves execution log output

✅

run_job

Jobs

Executes a job with options

❌

Job Options

When running jobs with the run_job tool, the server validates options before execution:

  • Required options must be provided (unless they have default values)

  • Enforced options must use values from the allowed list

  • Option summaries are displayed when validation fails

Example job options display:

Job Options:

  - version [REQUIRED]
      The version to deploy
      Allowed values (must be): '1.0', '1.1', '2.0'

  - environment [optional] (default: 'staging')
      Target environment
      Allowed values (suggested): 'dev', 'staging', 'prod'

  - dry_run [optional] (default: 'false')
      Run without making changes

Configuration

Environment Variable

Description

Default

RUNDECK_API_TOKEN

API token for authentication

(required)

RUNDECK_URL

Rundeck server URL

http://localhost:4440

RUNDECK_API_VERSION

API version number

44

Support

This MCP server is an open-source project. If assistance is required, please open an issue in the repository.

Contributing

If you are interested in contributing to this project, please refer to the PRD.md for architecture decisions and implementation patterns.

Available Tools

5 tools
get_executionA
Read-onlyIdempotent

Get detailed information about a specific execution.

Returns the full execution details including status, timing, node results,
and the arguments used.

Args:
    execution_id: The execution ID (integer)

Returns:
    Execution object with full details

Examples:
    >>> execution = get_execution(12345)
    >>> print(execution.status)
    'succeeded'
    >>> print(execution.duration_seconds)
    45.2

Inputs: execution_id (required). Returns: A job execution instance. Represents a single run of a job, including its statu…

get_execution_outputA
Read-onlyIdempotent

Get the log output from a job execution.

Retrieves log entries from the execution. For running executions, use the
'offset' parameter to poll for new output. The 'completed' field indicates
whether the execution has finished.

Args:
    execution_id: The execution ID (integer)
    last_lines: Return only the last N lines (overrides offset)
    max_lines: Maximum number of lines to return from offset
    offset: Byte offset to start reading from (for tailing)
    node: Filter output to a specific node

Returns:
    ExecutionOutput with log entries and metadata

Examples:
    Get all output:
    >>> output = get_execution_output(12345)
    >>> for entry in output.entries:
    ...     print(f"[{entry.level}] {entry.log}")

    Get last 50 lines:
    >>> output = get_execution_output(12345, last_lines=50)

    Tail running execution:
    >>> output = get_execution_output(12345, offset=0)
    >>> while not output.completed:
    ...     output = get_execution_output(12345, offset=output.offset)
    ...     # process new entries

Inputs: execution_id (required), last_lines, max_lines, offset, +1 more. Returns: Output/logs from a job execution. Contains the log entries and metadata about t…

get_jobA
Read-onlyIdempotent

Get detailed information about a specific job.

Returns the full job definition including all options displayed in a table
showing required status, defaults, and allowed values.

Args:
    job_id: The job UUID

Returns:
    Formatted string with job details and options table

Examples:
    >>> result = get_job("abc-123-def")
    >>> print(result)
    '## Deploy Application...'

Inputs: job_id (required). Returns: result

list_executionsA
Read-onlyIdempotent

List job executions with optional filtering.

Returns a list of executions matching the specified criteria. Filter by
project, job_id, status, or time range. Results are ordered by start time
(most recent first).

Args:
    query: Query parameters for filtering executions

Returns:
    List of Execution objects matching the query

Examples:
    List recent executions in a project:
    >>> result = list_executions(ExecutionQuery(project="myproject"))

    List failed executions for a specific job:
    >>> result = list_executions(ExecutionQuery(
    ...     job_id="abc-123-def",
    ...     status="failed"
    ... ))

    List executions from the last hour:
    >>> result = list_executions(ExecutionQuery(
    ...     project="myproject",
    ...     recent_filter="1h"
    ... ))

Inputs: query (required). Returns: response

list_jobsA
Read-onlyIdempotent

List jobs in a Rundeck project with optional filtering.

Returns a numbered markdown table of jobs. Use the # column to reference
jobs in subsequent commands (e.g., "run job 3").

Args:
    query: Query parameters for filtering jobs

Returns:
    Markdown table with numbered jobs

Examples:
    List all jobs in a project:
    >>> result = list_jobs(JobQuery(project="myproject"))

    Filter by group:
    >>> result = list_jobs(JobQuery(project="myproject", group_path="deploy/prod"))

    Search by name:
    >>> result = list_jobs(JobQuery(project="myproject", job_filter="backup"))

Inputs: query (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get_execution retrieves metadata, get_execution_output fetches logs, get_job shows job details, list_executions filters executions, and list_jobs lists jobs. The separation between execution-focused and job-focused tools is well-defined, preventing agent confusion.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern (get_execution, get_execution_output, get_job, list_executions, list_jobs) with clear verbs (get, list) and specific nouns. There are no deviations in style or convention throughout the set.

    Tool Count4/5

    Five tools is reasonable for a Rundeck server, covering core read operations for jobs and executions. However, the absence of tools for creating, updating, or running jobs makes the set feel slightly thin for full workflow automation, though it's well-scoped for monitoring and querying.

    Completeness2/5

    The tool set is severely incomplete for a Rundeck domain, which typically involves job execution and management. There are no tools to run jobs, create/update/delete jobs or executions, or manage projects—major gaps that will cause agent failures in automating Rundeck workflows beyond passive observation.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers