Rundeck MCP Server

Instructions

Implementation Reference

• rundeck_mcp/tools/jobs.py:52-79 (handler)

  The get_job tool handler: fetches job details from Rundeck API by job_id, handles response format, parses into Job model, and returns formatted markdown with job info and options table.
  def get_job(job_id: str) -> str: """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...' """ client = get_client() response = client.get(f"/job/{job_id}") # Handle list response (API returns list for single job lookup) if isinstance(response, list): if not response: raise ValueError("Job not found") response = response[0] job = _parse_job(response) return _format_job_details(job)
• rundeck_mcp/tools/__init__.py:6-21 (registration)

  Exports get_job from jobs.py and registers it in the read_tools list for safe, read-only operations.
  from .jobs import ( get_job, list_jobs, run_job, ) # Read-only tools (safe, non-destructive operations) read_tools = [ # Jobs list_jobs, get_job, # Executions list_executions, get_execution, get_execution_output, ]
• rundeck_mcp/server.py:108-110 (registration)

  Registers all tools from read_tools (including get_job) as read-only MCP tools with appropriate safety annotations.
  for tool in read_tools: add_read_only_tool(mcp, tool)
• rundeck_mcp/tools/jobs.py:79-169 (helper)

  Helper function called by get_job to format the Job object into a detailed markdown string with options table.
  return _format_job_details(job) def run_job(job_id: str, request: JobRunRequest | None = None, *, confirmed: bool = False) -> str: """Execute a Rundeck job with optional parameters. IMPORTANT: This is a two-step process: 1. First call without confirmed=True shows options and asks for confirmation 2. Second call with confirmed=True actually executes the job Before running, this tool validates that: - All required options are provided (or have defaults) - Option values match allowed values for enforced options Args: job_id: The job UUID to execute request: Optional execution parameters including options confirmed: Set to True to actually execute (after user confirms) Returns: Formatted string with options preview (step 1) or execution result (step 2) Examples: Step 1 - Preview options: >>> result = run_job("abc-123-def", JobRunRequest(options={"env": "prod"})) # Shows options table, asks user to confirm Step 2 - Execute after confirmation: >>> result = run_job("abc-123-def", JobRunRequest(options={"env": "prod"}), confirmed=True) """ client = get_client() # Fetch job to validate options job_response = client.get(f"/job/{job_id}") # Handle list response (API returns list for single job lookup) if isinstance(job_response, list): if not job_response: raise ValueError("Job not found") job_response = job_response[0] job = _parse_job(job_response) job_options = job_response.get("options") provided_options = request.options if request else None # Validate options is_valid, errors = validate_job_options(job_options, provided_options) if not is_valid: return _format_validation_error(job, errors, provided_options) # If not confirmed, show preview and ask for confirmation if not confirmed: return _format_run_preview(job, provided_options) # Build request body body = request.to_request_body() if request else {} # Execute job response = client.post(f"/job/{job_id}/run", json=body) return _format_run_response(_parse_run_response(response)) def _format_jobs_table(jobs: list[Job]) -> str: """Format jobs as a numbered markdown table. Args: jobs: List of Job objects to format Returns: Markdown table string with numbered jobs """ lines = [] lines.append("IMPORTANT: Display this markdown table exactly as shown - do not summarize or reformat.\n") lines.append(f"**{len(jobs)} jobs found.** Use # to reference jobs (e.g., 'run job 3'):\n") lines.append("| # | Name | Group | Job ID |") lines.append("|---|------|-------|--------|") for idx, job in enumerate(jobs, start=1): group = job.group or "-" lines.append(f"| {idx} | {job.name} | {group} | {job.id} |") lines.append("\n---") lines.append("STOP: You must show the table above to the user exactly as formatted. Do not summarize.") return "\n".join(lines) def _format_job_details(job: Job) -> str:
• rundeck_mcp/tools/jobs.py:382-419 (helper)

  Helper function to parse raw API job response into Job model instance, used by get_job.
  def _parse_job(data: dict[str, Any] | list) -> Job: """Parse job data from API response. Handles both single job responses (dict) and list responses. Converts option data to JobOption models. Args: data: Raw API response data Returns: Parsed Job model """ # Handle list response (take first item) if isinstance(data, list): if not data: raise ValueError("Empty job response") data = data[0] # Parse options if present options = None if data.get("options"): options = [_parse_job_option(opt) for opt in data["options"]] return Job( id=data["id"], name=data["name"], group=data.get("group"), project=data.get("project"), # May be None from /job/{id} endpoint description=data.get("description"), href=data.get("href"), permalink=data.get("permalink"), scheduled=data.get("scheduled", False), schedule_enabled=data.get("scheduleEnabled", True), enabled=data.get("enabled", True), average_duration=data.get("averageDuration"), options=options, )