Clone or download the server files
Install dependencies:
```
npm install
```
Build the TypeScript code:
```
npm run build
```

Setup

Prerequisites

Node.js 18+
GitHub Personal Access Token with appropriate permissions

GitHub Token Setup

Generate a GitHub Personal Access Token:
- Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
```
https://github.com/settings/personal-access-tokens
```
- Create a token with these scopes:
  - repo (full repository access)
  - workflow (update GitHub Action workflows)
  - contents:read (read access to see GitHub Action workflows)
  - contents:write (write access GitHub Action workflows)
  - actions:read (read access to GitHub Actions)
  - actions:write (write access to GitHub Actions)
Set the environment variable:
```
export GITHUB_TOKEN=your_token_here
```
OR
Navigate to your project directory and run the setup script:
```
cd github-actions-mcp
chmod +x setup.sh
./setup.sh
```

Required Permissions

Your GitHub token needs the following permissions for the target repositories:

Read: List workflows, get workflow details, view runs and jobs
Write: Create/update workflow files, trigger workflows
Actions: Cancel and rerun workflows

Usage

Running the Server

npm start

or for development

npm run dev

Tools

create_workflow

Create a new GitHub Actions workflow file in a repository.

Required inputs:

owner: Repository owner (username/organization)
repo: Repository name
path: Workflow file path (e.g., '.github/workflows/ci.yml')
name: Workflow name - should be descriptive and related to the workflow's purpose
on: Trigger events configuration
jobs: Jobs configuration

Optional inputs:

branch: Target branch (default: 'main')
commitMessage: Commit message (default: 'Add GitHub Actions workflow')

Example:

{
  "owner": "myorg",
  "repo": "myrepo",
  "path": ".github/workflows/ci.yml",
  "name": "CI Pipeline",
  "on": {
    "push": {
      "branches": ["main"]
    },
    "pull_request": {}
  },
  "jobs": {
    "test": {
      "runs-on": "ubuntu-latest",
      "steps": [
        {
          "name": "Checkout code",
          "uses": "actions/checkout@v4"
        },
        {
          "name": "Setup Node.js",
          "uses": "actions/setup-node@v4",
          "with": {
            "node-version": "18"
          }
        },
        {
          "name": "Install dependencies",
          "run": "npm install"
        },
        {
          "name": "Run tests",
          "run": "npm test"
        }
      ]
    }
  }
}

list_workflows

List all workflows in a repository.

Required inputs:

Categories

Current Category: github-actions

github-actions-mcp

github-actions-mcp-server