Rundeck MCP Server

Instructions

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"))

Implementation Reference

• rundeck_mcp/tools/jobs.py:15-49 (handler)

  The main handler function for the 'list_jobs' tool. It queries the Rundeck API using the provided JobQuery, parses the job data, and returns a formatted markdown table of jobs.

  def list_jobs(query: JobQuery) -> str:
      """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"))
      """
      client = get_client()
      params = query.to_params()
  
      response = client.get(f"/project/{query.project}/jobs", params=params)
  
      if not response:
          return "No jobs found."
  
      jobs = []
      for job_data in response:
          jobs.append(_parse_job(job_data))
  
      return _format_jobs_table(jobs)

• rundeck_mcp/models/jobs.py:122-177 (schema)

  Pydantic model defining the input schema for the list_jobs tool, including query parameters and method to convert to API params.

  class JobQuery(BaseModel):
      """Query parameters for listing jobs."""
  
      model_config = ConfigDict(extra="forbid")
  
      project: str = Field(description="Project name (required)")
      group_path: str | None = Field(
          default=None,
          description="Filter by group path. Use '*' for all groups, '' for root level only.",
      )
      job_filter: str | None = Field(
          default=None,
          description="Filter by job name (substring match)",
      )
      job_exact_filter: str | None = Field(
          default=None,
          description="Filter by exact job name",
      )
      group_path_exact: str | None = Field(
          default=None,
          description="Filter by exact group path",
      )
      scheduled_filter: bool | None = Field(
          default=None,
          description="Filter to only scheduled jobs (true) or only non-scheduled (false)",
      )
      tags: str | None = Field(
          default=None,
          description="Filter by tags (comma-separated)",
      )
      limit: int = Field(
          default=MAX_RESULTS,
          ge=1,
          le=MAX_RESULTS,
          description="Maximum number of results to return",
      )
  
      def to_params(self) -> dict[str, Any]:
          """Convert query to API parameters."""
          params: dict[str, Any] = {}
          if self.group_path is not None:
              params["groupPath"] = self.group_path
          if self.job_filter:
              params["jobFilter"] = self.job_filter
          if self.job_exact_filter:
              params["jobExactFilter"] = self.job_exact_filter
          if self.group_path_exact:
              params["groupPathExact"] = self.group_path_exact
          if self.scheduled_filter is not None:
              params["scheduledFilter"] = self.scheduled_filter
          if self.tags:
              params["tags"] = self.tags
          if self.limit:
              params["max"] = self.limit
          return params

• rundeck_mcp/tools/__init__.py:13-20 (registration)

  The list_jobs tool is imported and added to the read_tools list, which is later registered with the MCP server.

  read_tools = [
      # Jobs
      list_jobs,
      get_job,
      # Executions
      list_executions,
      get_execution,
      get_execution_output,

• rundeck_mcp/server.py:107-109 (registration)

  Registration of read_tools (including list_jobs) to the FastMCP server instance with read-only annotations.

  # Register read-only tools (always available)
  for tool in read_tools:
      add_read_only_tool(mcp, tool)

• rundeck_mcp/tools/jobs.py:144-166 (helper)

  Helper function to format the list of jobs into a numbered markdown table returned by the handler.

  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)