GitHub Actions MCP Server

What is GitHub Actions MCP Server about?

The server implements a set of tools that expose the GitHub Actions API to AI coding assistants (e.g., Claude Desktop, Codeium, Windsurf). By running the MCP server, assistants can perform complete workflow management—listing workflows, inspecting runs, triggering new runs, and handling cancellations or re‑runs—directly from the chat or code‑generation interface.

How to use GitHub Actions MCP Server?

1. Clone and build the repository.

   git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
   cd github-actions-mcp-server
   npm install
   npm run build   # or npm run build:win on Windows
   

2. Start the server (Unix/macOS):

   node dist/index.js
   

   (Windows users can run run-server.bat or npm run start).
3. Configure your AI assistant to point to the MCP server. Example for Claude Desktop and Codeium:

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

4. Provide a valid GitHub Personal Access Token with repo permissions via the GITHUB_PERSONAL_ACCESS_TOKEN environment variable.

Key features of GitHub Actions MCP Server

• Complete Workflow Management: list, retrieve, trigger, cancel, and rerun workflows.
• Workflow Run Analysis: detailed information about runs, jobs, and usage statistics.
• Robust Error Handling: clear messages with extra context for API failures.
• Flexible Type Validation: tolerant to GitHub API schema changes.
• Security‑Focused Design: request timeouts, rate‑limiting, and strict URL validation.
• Cross‑Assistant Compatibility: works with Claude Desktop, Codeium, Windsurf, etc.

Use cases of GitHub Actions MCP Server

• AI‑driven CI/CD automation: let a code‑assistant trigger a test suite after generating code.
• Workflow monitoring via chat: ask the assistant for the status of recent runs or job logs.
• Dynamic environment deployment: trigger deployment workflows with custom inputs from conversational prompts.
• Error diagnostics: retrieve failure details of a workflow run to suggest fixes.

FAQ

Q: Do I need a GitHub token? A: Yes, a personal access token with repo scope (or appropriate fine‑grained permissions) is required to avoid unauthenticated rate limits.

Q: Can I run the server without building it? A: The repository provides a batch file (run-server.bat) that builds if necessary, but the server must be compiled to JavaScript before it can run.

Q: How does rate limiting work? A: The server includes internal rate‑limiting logic to stay within GitHub API limits; exceeding the limit will return a clear error message.

Q: Is this server still maintained? A: The repo is slated for archiving because the official GitHub MCP server now supports Actions. It remains functional for existing setups.

Q: Which assistants are supported? A: Claude Desktop, Codeium, and Windsurf are explicitly documented, but any MCP‑compatible assistant can use the server.

GitHub Actions MCP Server

⚠️ Archive Notice: This repository will be archived soon as the official GitHub MCP server is adding Actions support. See github/github-mcp-server#491 for details on the official implementation.

MCP Server for the GitHub Actions API, enabling AI assistants to manage and operate GitHub Actions workflows. Compatible with multiple AI coding assistants including Claude Desktop, Codeium, and Windsurf.

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 AI Coding Assistants

This MCP server is compatible with multiple AI coding assistants including Claude Desktop, Codeium, and Windsurf.

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>"
      }
    }
  }
}

Codeium

Add the following configuration to your Codeium MCP config file (typically at ~/.codeium/windsurf/mcp_config.json on Unix-based systems or %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows):

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

Windsurf

Windsurf uses the same configuration format as Codeium. Add the server to your Windsurf MCP configuration as shown above for Codeium.

Build

Unix/Linux/macOS

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

Windows

For Windows systems, use the Windows-specific build command:

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

Alternatively, you can use the included batch file:

run-server.bat [optional-github-token]

This will create the necessary files in the dist directory that you'll need to run the MCP server.

Windows-Specific Instructions

Prerequisites

• Node.js (v14 or higher)
• npm (v6 or higher)

Running the Server on Windows

1. Using the batch file (simplest method):

   run-server.bat [optional-github-token]
   

   This will check if the build exists, build if needed, and start the server.

2. Using npm directly:

   npm run start
   

Setting GitHub Personal Access Token on Windows

For full functionality and to avoid rate limiting, you need to set your GitHub Personal Access Token.

Options:

1. Pass it as a parameter to the batch file:

   run-server.bat your_github_token_here
   

2. Set it as an environment variable:

   set GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
   npm run start
   

Troubleshooting Windows Issues

If you encounter issues:

1. Build errors: Make sure TypeScript is installed correctly.

   npm install -g typescript
   

2. Permission issues: Ensure you're running the commands in a command prompt with appropriate permissions.

3. Node.js errors: Verify you're using a compatible Node.js version.

   node --version
   

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.