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`

2. `get_workflow`

3. `get_workflow_usage`

4. `list_workflow_runs`

5. `get_workflow_run`

6. `get_workflow_run_jobs`

7. `trigger_workflow`

8. `cancel_workflow_run`

9. `rerun_workflow`

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": [
        "/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_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": [
        "/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_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:

2. Rate Limiting:

3. Type Validation Errors:

License

This MCP server is licensed under the MIT License.