Github Actions

GitHub Actions MCP Server

MCP Server for the GitHub Actions API, enabling AI assistants to manage and operate GitHub Actions workflows.

Features

Complete Workflow Management: List, view, trigger, cancel, and rerun workflows
Workflow Run Analysis: Get detailed information about workflow runs and their jobs
Comprehensive Error Handling: Clear error messages with enhanced details
Flexible Type Validation: Robust type checking with graceful handling of API variations
Security-Focused Design: Timeout handling, rate limiting, and strict URL validation

Tools

list_workflows
- List workflows in a GitHub repository
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - page (optional number): Page number for pagination
  - perPage (optional number): Results per page (max 100)
- Returns: List of workflows in the repository
get_workflow
- Get details of a specific workflow
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - workflowId (string or number): The ID of the workflow or filename
- Returns: Detailed information about the workflow
get_workflow_usage
- Get usage statistics of a workflow
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - workflowId (string or number): The ID of the workflow or filename
- Returns: Usage statistics including billable minutes
list_workflow_runs
- List all workflow runs for a repository or a specific workflow
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - workflowId (optional string or number): The ID of the workflow or filename
  - actor (optional string): Filter by user who triggered the workflow
  - branch (optional string): Filter by branch
  - event (optional string): Filter by event type
  - status (optional string): Filter by status
  - created (optional string): Filter by creation date (YYYY-MM-DD)
  - excludePullRequests (optional boolean): Exclude PR-triggered runs
  - checkSuiteId (optional number): Filter by check suite ID
  - page (optional number): Page number for pagination
  - perPage (optional number): Results per page (max 100)
- Returns: List of workflow runs matching the criteria
get_workflow_run
- Get details of a specific workflow run
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - runId (number): The ID of the workflow run
- Returns: Detailed information about the specific workflow run
get_workflow_run_jobs
- Get jobs for a specific workflow run
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - runId (number): The ID of the workflow run
  - filter (optional string): Filter jobs by completion status ('latest', 'all')
  - page (optional number): Page number for pagination
  - perPage (optional number): Results per page (max 100)
- Returns: List of jobs in the workflow run
trigger_workflow
- Trigger a workflow run
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - workflowId (string or number): The ID of the workflow or filename
  - ref (string): The reference to run the workflow on (branch, tag, or SHA)
  - inputs (optional object): Input parameters for the workflow
- Returns: Information about the triggered workflow run
cancel_workflow_run
- Cancel a workflow run
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - runId (number): The ID of the workflow run
- Returns: Status of the cancellation operation
rerun_workflow
- Re-run a workflow run
- Inputs:
  - owner (string): Repository owner (username or organization)
  - repo (string): Repository name
  - runId (number): The ID of the workflow run
- Returns: Status of the re-run operation

Usage with Claude Desktop

First, make sure you have built the project (see Build section below). Then, add the following to your claude_desktop_config.json:

1{
2  "mcpServers": {
3    "github-actions": {
4      "command": "node",
5      "args": [
6        "<path-to-your-project>/dist/index.js"
7      ],
8      "env": {
9        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
10      }
11    }
12  }
13}

Build

Clone the repository and build:

1git clone https://github.com/your-username/github-actions-mcp.git
2cd github-actions-mcp
3npm install
4npm run build

This will create the necessary files in the dist directory that you'll need to run the MCP server.

Usage Examples

List workflows in a repository:

1const result = await listWorkflows({
2  owner: "your-username",
3  repo: "your-repository"
4});

Trigger a workflow:

1const result = await triggerWorkflow({
2  owner: "your-username",
3  repo: "your-repository",
4  workflowId: "ci.yml",
5  ref: "main",
6  inputs: {
7    environment: "production"
8  }
9});

Troubleshooting

Common Issues

Authentication Errors:
- Ensure your GitHub token has the correct permissions
- Check that the token is correctly set as an environment variable
Rate Limiting:
- The server implements rate limiting to avoid hitting GitHub API limits
- If you encounter rate limit errors, reduce the frequency of requests
Type Validation Errors:
- GitHub API responses might sometimes differ from expected schemas
- The server implements flexible validation to handle most variations
- If you encounter persistent errors, please open an issue

License

This MCP server is licensed under the MIT License.

Contents