GitHub Actions MCP Server
Enables interaction with GitHub repositories to access and manage workflow files, including listing repositories, creating and updating workflow files, and managing repository contents through GitHub's API.
Provides comprehensive GitHub Actions management capabilities, including creating workflows, listing and retrieving workflow details, monitoring workflow runs, triggering workflows manually, canceling running workflows, and re-executing failed or completed workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GitHub Actions MCP Server create a CI workflow for my react app that runs tests on pull requests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: github-repo-mcp
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 installBuild 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-tokensCreate 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_hereOR
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 startor for development
npm run devTools
create_workflow
Create a new GitHub Actions workflow file in a repository.
Required inputs:
owner: Repository owner (username/organization)repo: Repository namepath: Workflow file path (e.g., '.github/workflows/ci.yml')name: Workflow name - should be descriptive and related to the workflow's purposeon: Trigger events configurationjobs: 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 ownerrepo: Repository name
Optional inputs:
page: Page number for paginationperPage: Results per page (max 100)
get_workflow
Get detailed information about a specific workflow.
Required inputs:
owner: Repository ownerrepo: Repository nameworkflowId: Workflow ID or filename
get_workflow_usage
Get usage statistics for a workflow (billing information).
Required inputs:
owner: Repository ownerrepo: Repository nameworkflowId: Workflow ID or filename
list_workflow_runs
List workflow runs with extensive filtering options.
Required inputs:
owner: Repository ownerrepo: Repository name
Optional inputs:
workflowId: Filter by specific workflowactor: Filter by user who triggered the runbranch: Filter by branchevent: Filter by trigger eventstatus: Filter by run statuscreated: Filter by creation date (YYYY-MM-DD)excludePullRequests: Exclude PR-triggered runscheckSuiteId: Filter by check suite IDpage: Page numberperPage: Results per page
get_workflow_run
Get detailed information about a specific workflow run.
Required inputs:
owner: Repository ownerrepo: Repository namerunId: Workflow run ID
get_workflow_run_jobs
Get jobs and steps for a specific workflow run.
Required inputs:
owner: Repository ownerrepo: Repository namerunId: Workflow run ID
Optional inputs:
filter: Filter jobs ('latest' or 'all')page: Page numberperPage: Results per page
trigger_workflow
Manually trigger a workflow using workflow_dispatch.
Required inputs:
owner: Repository ownerrepo: Repository nameworkflowId: Workflow ID or filenameref: 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 ownerrepo: Repository namerunId: Workflow run ID
rerun_workflow
Re-run a completed workflow.
Required inputs:
owner: Repository ownerrepo: Repository namerunId: 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_TOKENenvironment 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
workflowscope 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 startCommon 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 123452. 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 678903. 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.ymlContributing
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
Available Tools
10 toolscancel_workflow_runC
Cancel a workflow run
Inputs: owner (required), repo (required), runId (required).
create_workflowC
Create a new GitHub Actions workflow file
Inputs: jobs (required), name (required), on (required), owner (required), +4 more.
get_workflowC
Get details of a specific workflow
Inputs: owner (required), repo (required), workflowId (required).
get_workflow_runC
Get details of a specific workflow run
Inputs: owner (required), repo (required), runId (required).
get_workflow_run_jobsC
Get jobs for a specific workflow run
Inputs: owner (required), repo (required), runId (required), filter, +2 more.
get_workflow_usageC
Get usage statistics of a workflow
Inputs: owner (required), repo (required), workflowId (required).
list_workflow_runsC
List all workflow runs for a repository or specific workflow
Inputs: owner (required), repo (required), actor, branch, +8 more.
list_workflowsB
List workflows in a GitHub repository
Inputs: owner (required), repo (required), page, perPage.
rerun_workflowC
Re-run a workflow run
Inputs: owner (required), repo (required), runId (required).
trigger_workflowC
Trigger a workflow run
Inputs: owner (required), ref (required), repo (required), workflowId (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose targeting specific GitHub Actions resources and actions, with no overlap. For example, list_workflows enumerates workflows, get_workflow retrieves details, create_workflow adds new ones, and trigger_workflow initiates runs, making misselection unlikely.
All tools follow a consistent verb_noun pattern with snake_case, such as list_workflows, get_workflow_run, and cancel_workflow_run. This predictability aids agents in understanding and using the toolset effectively without confusion from mixed conventions.
With 10 tools, the server is well-scoped for managing GitHub Actions workflows, covering essential operations like listing, creating, triggering, and monitoring runs. Each tool earns its place without feeling excessive or insufficient for the domain.
The toolset provides complete CRUD and lifecycle coverage for GitHub Actions, including create_workflow, list_workflows, get_workflow, trigger_workflow, rerun_workflow, cancel_workflow_run, and monitoring via get_workflow_run and get_workflow_usage, with no obvious gaps or dead ends.
Related MCP Connectors
Model Context Protocol interface for Yari Infotech engineering & architectural advisory.
Model Context Protocol server for Studex tools, notifications, and profile integrations
A Model Context Protocol server for Wix AI tools
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables integration with GitHub Actions, allowing users to fetch available actions, get detailed information about specific actions, trigger workflow dispatch events, and fetch repository releases.53MIT
- AlicenseDqualityCmaintenanceModel Context Protocol server for Github Repo // Reading Github Repo3189 npm33MIT
- FlicenseNot gradedqualityNot gradedmaintenanceModel Context Protocol server that enables interaction with GitHub repositories, issues, pull requests, and search functionality through natural language.1-
- AlicenseNot gradedqualityDmaintenanceProvides a standardized interface for interacting with GitHub's tools and services through the Model Context Protocol, enabling unified API access and compatibility with MCP-compliant tools.1MIT