home / mcp / github workflow debugger mcp server

GitHub Workflow Debugger MCP Server

Fetches failed GitHub Actions runs, analyzes workflow run jobs, and suggests fixes via the GitHub API.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "maxteabag-githubworkflowmcp": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

You can diagnose and fix GitHub Actions workflow failures by using a Multi-Choice Prompt (MCP) server that talks to the GitHub API. It guides you through fetching failed runs, inspecting jobs and steps, identifying common failure patterns, and applying targeted fixes. This enables faster remediation and more reliable CI workflows.

How to use

To use this MCP with your MCP client, load the GitHub Workflow Debugger MCP and authenticate with a GitHub Personal Access Token that has the necessary permissions. Start by requesting recent failed workflow runs for your repository, then choose a specific run to analyze. Use the analysis results to view and modify the relevant workflow file if fixes are recommended. You can fetch the content of a workflow file and apply changes directly from the MCP tool when appropriate. This workflow helps you quickly pinpoint where failures occur and what changes will resolve them.

How to install

# Prerequisites
- Node.js 16 or higher
- npm or yarn

# Option 1: Install via Smithery (Claude Desktop)
npx -y @smithery/cli install @Maxteabag/githubworkflowmcp --client claude

# Option 2: Manual installation
# Clone the repository
git clone https://github.com/yourusername/github-workflow-debugger-mcp.git
cd github-workflow-debugger-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Link the binary for local use
npm link

Configuration and usage details

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Security notes

You must protect your GitHub Personal Access Token. Store it securely and provide it only to trusted MCP clients. The token should be kept out of source control and rotated regularly to minimize risk.

Available tools

get-failed-workflow-runs

Fetches recent failed workflow runs for a repository to identify failing workflows and prioritize investigation.

get-workflow-run-jobs

Retrieves the jobs for a specific workflow run to analyze where failures occur within the run.

get-workflow-file

Retrieves the content of a workflow file so you can view the current configuration and determine if changes are needed.

update-workflow-file

Updates a workflow file with fixes or improvements to resolve failures or optimize workflows.

analyze-workflow-failure

Analyzes a failed workflow run and suggests concrete fixes based on observed patterns and best practices.