GitHub Actions MCP server for AI agents

The GitHub Actions MCP Server provides an interface for AI assistants to manage GitHub Actions workflows through a standardized Model Context Protocol. It enables AI tools to list, view, trigger, cancel, and analyze GitHub Actions workflows.

Installation

Prerequisites

Node.js (v14 or higher)
npm (v6 or higher)
GitHub Personal Access Token

Setting Up on Unix/Linux/macOS

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

Setting Up on Windows

Using npm directly:

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

Or use the included batch file:

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

Configuration

Setting GitHub Personal Access Token

For full functionality, you need to set your GitHub Personal Access Token:

On Unix/Linux/macOS:

export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

On Windows:

set GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

Integrating with AI Assistants

Claude Desktop Integration

Add this 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 Integration

Add this 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 Integration

Windsurf uses the same configuration format as Codeium. Add the server configuration as shown above.

Available Tools

Listing Workflows

const result = await listWorkflows({
  owner: "your-username",
  repo: "your-repository",
  page: 1,          // optional
  perPage: 30       // optional
});

Getting Workflow Details

const result = await getWorkflow({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml" // or workflow ID number
});

Getting Workflow Usage Statistics

const result = await getWorkflowUsage({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml" // or workflow ID number
});

Listing Workflow Runs

const result = await listWorkflowRuns({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml",  // optional
  actor: "username",     // optional
  branch: "main",        // optional
  status: "completed",   // optional
  page: 1,               // optional
  perPage: 30            // optional
});

Getting Workflow Run Details

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

Getting Workflow Run Jobs

const result = await getWorkflowRunJobs({
  owner: "your-username",
  repo: "your-repository",
  runId: 12345678,
  filter: "latest",   // optional: 'latest' or 'all'
  page: 1,            // optional
  perPage: 30         // optional
});

Triggering a Workflow

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

Cancelling a Workflow Run

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

Re-running a Workflow

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

Troubleshooting

Common Issues

Authentication Errors: Verify your GitHub token has the correct permissions and is properly set as an environment variable.
Rate Limiting: If you encounter rate limit errors, reduce the frequency of requests to the GitHub API.
Type Validation Errors: If you encounter schema validation errors, check that your inputs match the expected format.
Windows-Specific Issues:
- Make sure TypeScript is installed: npm install -g typescript
- Run commands in a command prompt with appropriate permissions
- Verify you're using a compatible Node.js version: node --version

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect