GitHub Actions MCP Server

A Model Context Protocol (MCP) server that provides comprehensive GitHub Actions management capabilities. This server allows you to create, manage, monitor, and interact with GitHub Actions workflows through a standardized interface.

Content

Features

Workflow Management

Create Workflow: Create new GitHub Actions workflow files
List Workflows: Get all workflows in a repository
Get Workflow: Retrieve detailed information about a specific workflow
Get Workflow Usage: View usage statistics and billing information

Workflow Runs

List Workflow Runs: List all workflow runs with filtering options
Get Workflow Run: Get detailed information about a specific run
Get Workflow Run Jobs: View jobs and steps for a workflow run
Trigger Workflow: Manually trigger a workflow dispatch event
Cancel Workflow Run: Cancel a running workflow
Rerun Workflow: Re-execute a failed or completed workflow

Installation

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:

owner: Repository owner
repo: Repository name

Optional inputs:

page: Page number for pagination
perPage: Results per page (max 100)

get_workflow

Get detailed information about a specific workflow.

Required inputs:

owner: Repository owner
repo: Repository name
workflowId: Workflow ID or filename

get_workflow_usage

Get usage statistics for a workflow (billing information).

Required inputs:

owner: Repository owner
repo: Repository name
workflowId: Workflow ID or filename

list_workflow_runs

List workflow runs with extensive filtering options.

Required inputs:

owner: Repository owner
repo: Repository name

Optional inputs:

workflowId: Filter by specific workflow
actor: Filter by user who triggered the run
branch: Filter by branch
event: Filter by trigger event
status: Filter by run status
created: Filter by creation date (YYYY-MM-DD)
excludePullRequests: Exclude PR-triggered runs
checkSuiteId: Filter by check suite ID
page: Page number
perPage: Results per page

get_workflow_run

Get detailed information about a specific workflow run.

Required inputs:

owner: Repository owner
repo: Repository name
runId: Workflow run ID

get_workflow_run_jobs

Get jobs and steps for a specific workflow run.

Required inputs:

owner: Repository owner
repo: Repository name
runId: Workflow run ID

Optional inputs:

filter: Filter jobs ('latest' or 'all')
page: Page number
perPage: Results per page

trigger_workflow

Manually trigger a workflow using workflow_dispatch.

Required inputs:

owner: Repository owner
repo: Repository name
workflowId: Workflow ID or filename
ref: Branch, tag, or commit SHA to run on

Optional inputs:

inputs: Input parameters for the workflow

cancel_workflow_run

Cancel a running workflow.

Required inputs:

owner: Repository owner
repo: Repository name
runId: Workflow run ID

rerun_workflow

Re-run a completed workflow.

Required inputs:

owner: Repository owner
repo: Repository name
runId: Workflow run ID

Configuration File Integration

You can also use this server with MCP configuration files. Add to your MCP settings:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "github-token",
        "description": "GitHub personal access token",
        "password": true
      }
    ],
    "servers": {
      "GitHub Actions": {
        "command": "node",
        "args": ["/path/to/github-actions-mcp-server/dist/index.js"],
        "env": {
          "GITHUB_TOKEN": "${input:github-token}"
        }
      }
    }
  }
}

Error Handling

The server provides comprehensive error handling:

Authentication errors: Invalid or expired GitHub tokens
Permission errors: Insufficient repository access
Rate limiting: GitHub API rate limit exceeded
Validation errors: Invalid input parameters
Network errors: Connection issues with GitHub API

Troubleshooting

Common Issues

Token Authentication Fails

Verify your GitHub token is valid and not expired
Check that the token has the required scopes
Ensure the GITHUB_TOKEN environment variable is set

Permission Denied

Verify your token has access to the target repository
For organization repositories, check if additional permissions are needed
Ensure your token has the workflow scope for creating/modifying workflows

Rate Limiting

GitHub API has rate limits (5000 requests/hour for authenticated requests)
Implement retry logic with exponential backoff if needed
Consider using multiple tokens for high-volume operations

Workflow Creation Fails

Check that the workflow path starts with .github/workflows/
Ensure the YAML syntax is valid
Verify the target branch exists

Debug Mode

For debugging, you can run the server with additional logging:

DEBUG=* npm start

Common Use Cases

1. Monitoring Workflow Health

# List recent workflow runs to check status
list_workflow_runs --owner myorg --repo myapp --status completed --per_page 10

# Get details of a failed run
get_workflow_run --owner myorg --repo myapp --run_id 12345

# View job details to identify failure points
get_workflow_run_jobs --owner myorg --repo myapp --run_id 12345

2. Managing Deployments

# Trigger a deployment workflow
trigger_workflow --owner myorg --repo myapp --workflow_id deploy.yml --ref main --inputs '{"environment": "production"}'

# Monitor the deployment
list_workflow_runs --owner myorg --repo myapp --workflow_id deploy.yml --status in_progress

# Cancel if needed
cancel_workflow_run --owner myorg --repo myapp --run_id 67890

3. Workflow Maintenance

# List all workflows to review
list_workflows --owner myorg --repo myapp

# Check workflow usage for billing
get_workflow_usage --owner myorg --repo myapp --workflow_id ci.yml

# Get workflow details for optimization
get_workflow --owner myorg --repo myapp --workflow_id ci.yml

Contributing

We welcome contributions to the GitHub Actions MCP Server! Whether you're fixing bugs, improving documentation, adding new features, or providing feedback, your help is appreciated.

License

MIT License

You must be authenticated.

security – no known vulnerabilities

license - not found

quality - confirmed to work

Tools

View all tools

GitHub Actions Model Context Protocol Server that allows you to create, manage, monitor, and interact with workflows.

Related MCP Servers

git MCP serverofficial
modelcontextprotocol
-
security
A
license
-
quality
A Model Context Protocol server for Git repository interaction and automation. This server provides tools to read, search, and manipulate Git repositories via Large Language Models.
Last updated -
12
52,814
Python
MIT License
GitHub MCP Server
PoliTwit1984
A
security
F
license
A
quality
A Model Context Protocol server that enables AI models to interact with GitHub's API, allowing for repository creation and management with descriptions, topics, and website URLs through natural language commands.
Last updated -
1
JavaScript
GitHub MCP Server
cyanheads
-
security
A
license
-
quality
A Model Context Protocol server that enables LLM agents to manage GitHub repositories, issues, pull requests, branches, files, and releases through a standardized interface.
Last updated -
2
TypeScript
Apache 2.0
GitHub MCP Server
renantrendt
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to perform GitHub operations including repository management, file operations, issue tracking, and pull request creation.
Last updated -
1
TypeScript

View all related MCP servers