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.
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 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
or for development
Tools
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:
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:
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:
Common Use Cases
1. Monitoring Workflow Health
2. Managing Deployments
3. Workflow Maintenance
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
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
GitHub Actions Model Context Protocol Server that allows you to create, manage, monitor, and interact with workflows.
Related MCP Servers
- AsecurityFlicenseAqualityA 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 -
- -securityAlicense-qualityA 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 -6,7169Apache 2.0
- -securityFlicense-qualityA 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
- AsecurityFlicenseAqualityA 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.Last updated -4101