📌Overview

Purpose: The MCP Server for GitHub Actions enables AI assistants to efficiently manage and operate GitHub Actions workflows.

Overview: This framework provides a set of tools for comprehensive workflow management within GitHub Actions, allowing users to seamlessly list, view, trigger, and manage workflow runs while maintaining optimal error handling and security measures.

Key Features:

• Complete Workflow Management: Users can list, view, trigger, cancel, and rerun workflows, ensuring a streamlined process for managing various actions.

• Workflow Run Analysis: Gain in-depth insights into workflow runs and their respective jobs, helping to understand performance and outcomes.

• Comprehensive Error Handling: Features clear and detailed error messages, enhancing user experience and troubleshooting capabilities.

• Flexible Type Validation: Robust type checking accommodates variations in API responses, promoting reliability and accuracy in handling data.

• Security-Focused Design: Implements timeout handling, rate limiting, and strict URL validation to protect against potential security risks.

---

GitHub Actions MCP Server

MCP Server for the GitHub Actions API, enabling AI assistants to manage and operate GitHub Actions workflows.

Features

• Complete Workflow Management: List, view, trigger, cancel, and rerun workflows
• Workflow Run Analysis: Get detailed information about workflow runs and their jobs
• Comprehensive Error Handling: Clear error messages with enhanced details
• Flexible Type Validation: Robust type checking with graceful handling of API variations
• Security-Focused Design: Timeout handling, rate limiting, and strict URL validation

Tools

1. list_workflows
   List workflows in a GitHub repository
   Inputs:

   • owner (string): Repository owner (username or organization)
   • repo (string): Repository name
   • page (optional number): Page number for pagination
   • perPage (optional number): Results per page (max 100)
     Returns: List of workflows in the repository

2. get_workflow
   Get details of a specific workflow
   Inputs:

   • owner (string)
   • repo (string)
   • workflowId (string or number): The ID of the workflow or filename
     Returns: Detailed information about the workflow

3. get_workflow_usage
   Get usage statistics of a workflow
   Inputs:

   • owner (string)
   • repo (string)
   • workflowId (string or number)
     Returns: Usage statistics including billable minutes

4. list_workflow_runs
   List all workflow runs for a repository or a specific workflow
   Inputs include filtering options such as actor, branch, event, status, creation date, and pagination parameters.
   Returns: List of workflow runs matching the criteria

5. get_workflow_run
   Get details of a specific workflow run
   Inputs:

   • owner (string)
   • repo (string)
   • runId (number): The ID of the workflow run
     Returns: Detailed information about the specific workflow run

6. get_workflow_run_jobs
   Get jobs for a specific workflow run
   Inputs include optional filter and pagination parameters.
   Returns: List of jobs in the workflow run

7. trigger_workflow
   Trigger a workflow run
   Inputs:

   • owner (string)
   • repo (string)
   • workflowId (string or number)
   • ref (string): The reference to run the workflow on (branch, tag, or SHA)
   • inputs (optional object): Input parameters for the workflow
     Returns: Information about the triggered workflow run

8. cancel_workflow_run
   Cancel a workflow run
   Inputs:

   • owner (string)
   • repo (string)
   • runId (number)
     Returns: Status of the cancellation operation

9. rerun_workflow
   Re-run a workflow run
   Inputs:

   • owner (string)
   • repo (string)
   • runId (number)
     Returns: Status of the re-run operation

Usage with Claude Desktop

First, build the project (see Build section). Then add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "github-actions": {
      "command": "node",
      "args": [
        "<path-to-mcp-server>/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Build

Clone the repository and build:

git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
cd github-actions-mcp-server
npm install
npm run build

This will create the necessary files in the dist directory to run the MCP server.

Usage Examples

List workflows in a repository:

const result = await listWorkflows({
  owner: "your-username",
  repo: "your-repository"
});

Trigger a workflow:

const result = await triggerWorkflow({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml",
  ref: "main",
  inputs: {
    environment: "production"
  }
});

Troubleshooting

Common Issues

1. Authentication Errors

   • Ensure your GitHub token has the correct permissions
   • Verify the token is correctly set as an environment variable

2. Rate Limiting

   • The server implements rate limiting to avoid hitting GitHub API limits
   • Reduce request frequency if encountering rate limit errors

3. Type Validation Errors

   • GitHub API responses might vary from expected schemas
   • The server uses flexible validation to handle variations
   • For persistent errors, please open an issue

License

This MCP server is licensed under the MIT License.