GitHub Actions MCP Server

Implementation Reference

• src/operations/actions.ts:138-178 (handler)

  The main handler function that executes the tool logic: validates inputs, constructs GitHub API URL, fetches workflow runs, and parses response using WorkflowRunsSchema.

  export async function listWorkflowRuns(
    owner: string, 
    repo: string, 
    options: {
      workflowId?: string | number,
      actor?: string,
      branch?: string,
      event?: string,
      status?: string,
      created?: string,
      excludePullRequests?: boolean,
      checkSuiteId?: number,
      page?: number,
      perPage?: number
    } = {}
  ) {
    owner = validateOwnerName(owner);
    repo = validateRepositoryName(repo);
  
    let url;
    if (options.workflowId) {
      url = `https://api.github.com/repos/${owner}/${repo}/actions/workflows/${options.workflowId}/runs`;
    } else {
      url = `https://api.github.com/repos/${owner}/${repo}/actions/runs`;
    }
  
    url = buildUrl(url, {
      actor: options.actor,
      branch: options.branch,
      event: options.event,
      status: options.status,
      created: options.created,
      exclude_pull_requests: options.excludePullRequests ? "true" : undefined,
      check_suite_id: options.checkSuiteId,
      page: options.page,
      per_page: options.perPage
    });
  
    const response = await githubRequest(url);
    return WorkflowRunsSchema.parse(response);
  }

• src/operations/actions.ts:35-48 (schema)

  Zod schema defining input parameters and validation for the list_workflow_runs tool.

  export const ListWorkflowRunsSchema = z.object({
    owner: z.string().describe("Repository owner (username or organization)"),
    repo: z.string().describe("Repository name"),
    workflowId: z.string().optional().describe("The ID of the workflow or filename (string or number)"),
    actor: z.string().optional().describe("Returns someone's workflow runs. Use the login for the user"),
    branch: z.string().optional().describe("Returns workflow runs associated with a branch"),
    event: z.string().optional().describe("Returns workflow runs triggered by the event"),
    status: z.enum(['completed', 'action_required', 'cancelled', 'failure', 'neutral', 'skipped', 'stale', 'success', 'timed_out', 'in_progress', 'queued', 'requested', 'waiting', 'pending']).optional().describe("Returns workflow runs with the check run status"),
    created: z.string().optional().describe("Returns workflow runs created within date range (YYYY-MM-DD)"),
    excludePullRequests: z.boolean().optional().describe("If true, pull requests are omitted from the response"),
    checkSuiteId: z.number().optional().describe("Returns workflow runs with the check_suite_id"),
    page: z.number().optional().describe("Page number for pagination"),
    perPage: z.number().optional().describe("Results per page (max 100)"),
  });

• src/index.ts:177-185 (registration)

  MCP server tool registration for 'list_workflow_runs', providing schema and wrapper handler that delegates to the main implementation.

  server.tool(
      "list_workflow_runs",
      actions.ListWorkflowRunsSchema.shape,
      async (request: any) => {
          const { owner, repo, workflowId, ...options } = request;
          const result = await actions.listWorkflowRuns(owner, repo, { workflowId, ...options });
          return { content: [{ type: "text", text: JSON.stringify(result) }] };
      }
  );