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): Repository owner (username or organization)
     • repo (string): Repository name
     • 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): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (string or number): The ID of the workflow or filename
   • Returns: Usage statistics including billable minutes

4. list_workflow_runs

   • List all workflow runs for a repository or a specific workflow
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (optional string or number): The ID of the workflow or filename
     • actor (optional string): Filter by user who triggered the workflow
     • branch (optional string): Filter by branch
     • event (optional string): Filter by event type
     • status (optional string): Filter by status
     • created (optional string): Filter by creation date (YYYY-MM-DD)
     • excludePullRequests (optional boolean): Exclude PR-triggered runs
     • checkSuiteId (optional number): Filter by check suite ID
     • page (optional number): Page number for pagination
     • perPage (optional number): Results per page (max 100)
   • Returns: List of workflow runs matching the criteria

5. get_workflow_run

   • Get details of a specific workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • 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:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
     • filter (optional string): Filter jobs by completion status ('latest', 'all')
     • page (optional number): Page number for pagination
     • perPage (optional number): Results per page (max 100)
   • Returns: List of jobs in the workflow run

7. trigger_workflow

   • Trigger a workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (string or number): The ID of the workflow or filename
     • 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): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
   • Returns: Status of the cancellation operation

9. rerun_workflow

   • Re-run a workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
   • Returns: Status of the re-run operation

Usage with Claude Desktop

First, make sure you have built the project (see Build section below). 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 that you'll need 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
   • Check that the token is correctly set as an environment variable

2. Rate Limiting:

   • The server implements rate limiting to avoid hitting GitHub API limits
   • If you encounter rate limit errors, reduce the frequency of requests

3. Type Validation Errors:

   • GitHub API responses might sometimes differ from expected schemas
   • The server implements flexible validation to handle most variations
   • If you encounter persistent errors, please open an issue

License

This MCP server is licensed under the MIT License.