Github Actions MCP Server

🚀 GitHub Actions MCP Server

The MCP server for GitHub Actions enables AI assistants to manage and operate GitHub Actions workflows.

🚀 Quick Start

This is a MCP server for GitHub Actions, which empowers AI assistants to manage and operate GitHub Actions workflows.

✨ Features

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

📚 Documentation

Tool List

1. list_workflows

   • List workflows in a repository.
   • Input parameters:
     • owner (string): Repository owner (username or organization).
     • repo (string): Repository name.
     • page (optional number): Page number for pagination.
     • perPage (optional number): Number of results per page (maximum 100).
   • Return value: A list of workflows in the repository.

2. get_workflows

   • Get workflows of a specified owner.
   • Input parameters:
     • owner (string): Repository owner.
   • Return value: Detailed workflow information of the owner.

3. trigger_workflow

   • Trigger a specified workflow run.
   • Input parameters:
     • owner (string): Repository owner.
     • repo (string): Repository name.
     • workflow_id (string): Workflow ID.
     • ref (string): Code reference (branch, tag, or commit hash).
     • inputs (object): Input parameters passed to the workflow.
   • Return value: Status information of the triggered run.

4. get_workflow_run

   • Get detailed information about a specified workflow run.
   • Input parameters:
     • owner (string): Repository owner.
     • repo (string): Repository name.
     • run_id (string): Run ID.
   • Return value: Detailed information about the run.

5. list_workflow_runs

   • List all runs of a specified workflow.
   • Input parameters:
     • owner (string): Repository owner.
     • repo (string): Repository name.
     • workflow_id (string): Workflow ID.
   • Return value: A list of workflow runs.

💻 Usage Examples

Basic Usage

Listing Workflows

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

Triggering a Workflow

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

Configuration Example

Add the following to claude_desktop_config.json:

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

📦 Installation

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 generate the necessary files in the dist directory to run the MCP server.

📚 Documentation

Frequently Asked Questions

1. Authentication Errors:

   • Ensure your GitHub token has the correct permissions.
   • Check if 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 request frequency.

3. Type Validation Errors:

   • GitHub API responses may differ from the expected schema.
   • The server implements flexible validation to handle most variations.
   • If you encounter persistent errors, open an issue report.

📄 License

This MCP server is released under the MIT License.