Rundeck MCP Server

Instructions

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)