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

1. list_workflows
2. List workflows in a GitHub repository
3. 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)

4. Returns: List of workflows in the repository

5. get_workflow

6. Get details of a specific workflow
7. Inputs:
   • owner (string): Repository owner (username or organization)
   • repo (string): Repository name
   • workflowId (string or number): The ID of the workflow or filename

8. Returns: Detailed information about the workflow

9. get_workflow_usage

10. Get usage statistics of a workflow
11. Inputs:
    • owner (string): Repository owner (username or organization)
    • repo (string): Repository name
    • workflowId (string or number): The ID of the workflow or filename

12. Returns: Usage statistics including billable minutes

13. list_workflow_runs

14. List all workflow runs for a repository or a specific workflow
15. 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)

16. Returns: List of workflow runs matching the criteria

17. get_workflow_run

18. Get details of a specific workflow run
19. Inputs:
    • owner (string): Repository owner (username or organization)
    • repo (string): Repository name
    • runId (number): The ID of the workflow run

20. Returns: Detailed information about the specific workflow run

21. get_workflow_run_jobs

22. Get jobs for a specific workflow run
23. 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)

24. Returns: List of jobs in the workflow run

25. trigger_workflow

26. Trigger a workflow run
27. 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

28. Returns: Information about the triggered workflow run

29. cancel_workflow_run

30. Cancel a workflow run
31. Inputs:
    • owner (string): Repository owner (username or organization)
    • repo (string): Repository name
    • runId (number): The ID of the workflow run

32. Returns: Status of the cancellation operation

33. rerun_workflow

34. Re-run a workflow run
35. Inputs:
    • owner (string): Repository owner (username or organization)
    • repo (string): Repository name
    • runId (number): The ID of the workflow run
36. 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:

{
  "mcpServers": {
    "github-actions": {
      "command": "node",
      "args": [
        "<path-to-mcp-server>/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Build

Clone the repository and build:

git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
cd github-actions-mcp-server
npm install
npm 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:

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

Trigger a workflow:

const result = await triggerWorkflow({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml",
  ref: "main",
  inputs: {
    environment: "production"
  }
});

Troubleshooting

Common Issues

1. Authentication Errors:
2. Ensure your GitHub token has the correct permissions

3. Check that the token is correctly set as an environment variable

4. Rate Limiting:

5. The server implements rate limiting to avoid hitting GitHub API limits

6. If you encounter rate limit errors, reduce the frequency of requests

7. Type Validation Errors:

8. GitHub API responses might sometimes differ from expected schemas
9. The server implements flexible validation to handle most variations
10. If you encounter persistent errors, please open an issue

License

This MCP server is licensed under the MIT License.