GitHub Workflow Fix-and-Retry MCP Server
This server lets you monitor and control GitHub Actions fix-and-retry chains, where failing opt-in workflows are automatically fixed by OpenCode and retried.
List fix-and-retry chains, optionally filtered by state
Get details of a single chain by ID
Trigger an immediate retry of a chain
Pause a running, waiting, or fix-error chain
Resume a paused chain
Create a GitHub issue for a chain
Override configuration such as
gh_oc_autoorretry_delays_minCheck server health, DB status, and chain counts
Provides tools for interacting with GitHub repositories to manage fix-and-retry chains, including rerunning failed workflows and opening issues.
Monitors failing GitHub Actions workflows that opt in via a marker, automatically applies fixes with OpenCode, and retries the runs until they succeed or the retry budget is exhausted.
GitHub Workflow Fix-and-Retry MCP Server
Monitor failing GitHub Actions workflows, auto-fix them with OpenCode,
and retry the run — driven by a workflow_run webhook, coordinated through an MCP server.
When a workflow that opts in via a # self-heal: true marker in its YAML fails, a
"fix-and-retry chain" is started: wait for the configured retry delays, run OpenCode
on a worktree of the failing branch to produce a fix, push it, re-run the workflow,
and on repeated failure open a GitHub issue. The MCP server surfaces the chains
(list_chains, get_chain, pause_chain, resume_chain, retry_now,
create_issue_now, set_config, health) to any MCP client.
Precheck: OpenCode via curl
Before anything else, make sure OpenCode is installed and reachable. OpenCode is
commonly installed with curl and is not on PATH by default (e.g. it lands
in /root/.opencode/bin/opencode). The daemon will not find it unless you point
OPENCODE_BIN at the binary:
# install OpenCode (curl) — note where it lands
curl -fsSL https://opencode.ai/install | sh
# /root/.opencode/bin/opencode (or similar, depending on the installer)
# tell the daemon where to find it
export OPENCODE_BIN=/root/.opencode/bin/opencodeIf OPENCODE_BIN is unset, the daemon falls back to opencode on PATH and the
fix runner will fail with "executable not found" on the first chain. Verify with:
test -x "$OPENCODE_BIN" && echo "ok" || echo "OPENCODE_BIN not executable"Related MCP server: cc-agent
Architecture
GitHub Actions (workflow_run event)
│ POST /webhook/github (HMAC-SHA256 verified)
▼
Starlette webhook daemon ──► Service (chain state machine)
│ │
│ ├─► db (SQLite: chains / retries / events)
│ ├─► GitHub client (open issue, rerun)
│ └─► OpenCodeRunner (clone → fix → push)
▼
MCP server (stdio) ──► chain control tools for AI clientsTwo runnable entry points:
Daemon:
python -m gh_workflow_fix— Starlette webhook server on port18080(configurable) plus a scheduler tick that picks up due chains.MCP server:
python -m gh_workflow_fix.mcp— stdio MCP server with the chain control tools.
Why the daemon is required
The MCP server alone is stateless — it reads state.db but never writes to it.
Without the daemon running on the same machine:
list_chainsreturns[]andget_chainreturns404— there is no data.healthreturns{"ok": true}but with"latest_event": nulland"chains": {}.retry_now,pause_chain,resume_chainandcreate_issue_nowhave nothing to act on.
The daemon is what creates the data: it receives workflow_run webhooks from
GitHub, runs OpenCode on worktrees to produce fixes, pushes them, re-runs the
workflow, and records every chain, retry and event in state.db. The MCP server
is only a control surface over that data.
The daemon must run on a machine that can:
receive inbound HTTPS webhooks from GitHub (port
18080must be reachable),clone and push to the monitored repository (needs git credentials with write access),
run the
opencodebinary (set viaOPENCODE_BIN),keep
DATA_DIRpersistent across restarts (chains and retry state live there).
A stateless container (e.g. a remote MCP host with its own fresh database) exposes a valid but empty tool surface — it cannot fix anything by itself.
Installation
pip install gh-workflow-fix-mcpRequires Python >= 3.11 and OpenCode installed for the fix
runner (the binary path is set with OPENCODE_BIN; it must be able to push to the
repository of the failing workflow). See Precheck: OpenCode via curl
above — if OPENCODE_BIN is unset, the fix runner will fail on the first chain.
Configuration
All settings come from environment variables. Only GH_TOKEN, GH_REPO,
GH_OC_AUTO and WEBHOOK_SECRET are required.
Variable | Required | Description | Default |
| yes | GitHub PAT with | — |
| yes | Repository to monitor, | — |
| yes | Automatically run OpenCode fixes ( | — |
| yes | Secret for HMAC verification (same value as the GitHub webhook) | — |
| no | Marker comment that opts a workflow into self-healing |
|
| no | Comma-separated delays (minutes) before attempts 1, 2, 3… |
|
| no | Where DB and worktrees live |
|
| no | Path to the |
|
| no | Model to pass to | unset |
| no | GitHub API base URL (for GHES) |
|
| no | Bind address of the daemon |
|
| no | Timeout for a single OpenCode fix run |
|
| no | Scheduler tick interval in seconds |
|
Opt-in marker
A workflow only becomes a fix candidate when its YAML contains the marker
(default # self-heal: true) as a comment. For example:
name: CI
# self-heal: true
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- run: echo helloWebhook setup (GitHub)
Repository → Settings → Webhooks → Add webhook.
Payload URL:
https://your-host:18080/webhook/github.Content type:
application/json.Events: "Let me select individual events" → Workflow runs (
workflow_run).Secret: the same value as
WEBHOOK_SECRET.Save; GitHub sends a test ping which is ignored — only
workflow_runevents are processed.
Only failing runs of opt-in workflows create chains; successful runs are recorded in the events table and ignored.
Running the daemon
export GH_TOKEN=... GH_REPO=owner/repo GH_OC_AUTO=true WEBHOOK_SECRET=...
python -m gh_workflow_fixThe daemon exposes POST /webhook/github (HMAC verified) and GET /healthz
({"ok": true, "db": ..., "tick": ...}).
Running on your own server (step by step)
Install (Python >= 3.11, OpenCode binary on
PATHor setOPENCODE_BIN):pip install gh-workflow-fix-mcpCreate a
.envwith the four required variables (see Configuration).Start the daemon (same machine as the MCP server):
export GH_TOKEN=... GH_REPO=owner/repo GH_OC_AUTO=true WEBHOOK_SECRET=... python -m gh_workflow_fixConfigure the GitHub webhook — Webhook setup (GitHub). Make sure the Payload URL is reachable from the internet and stays stable.
Start the MCP server (shares the daemon's environment and
DATA_DIR):python -m gh_workflow_fix.mcpConnect your MCP client — MCP client setup.
After a failing run of an opt-in workflow, the daemon creates a chain and the MCP
tools become useful: list_chains shows it, retry_now / pause_chain /
resume_chain control it, and create_issue_now opens a GitHub issue when the
retry budget is exhausted.
MCP client setup
Add to your MCP configuration, e.g. for OpenCode (opencode.json):
{
"mcp": {
"gh-workflow-fix": {
"type": "local",
"command": ["python", "-m", "gh_workflow_fix.mcp"],
"enabled": true
}
}
}The MCP server reads the same environment as the daemon. Run it locally on the same
machine as the daemon (they share DATA_DIR/state.db).
Note: a remote/stateless MCP host (e.g. a hosted MCP registry with its own fresh database) will answer
initialize,tools/listandhealth, but itslist_chainswill be empty and its mutating tools will have nothing to act on. Use the local configuration above if you want to manage real chains.
MCP tools
Tool | Description |
| List fix-and-retry chains, optionally filtered by state |
| Get a single chain by ID |
| Schedule a chain for immediate retry |
| Pause a chain (only if running, waiting, or fix_error) |
| Resume a paused chain |
| Create a GitHub issue for a chain |
| Set a config override ( |
| Health check with DB status and chain counts |
Chain states
running → fix attempt on a worktree → either waiting (fix pushed / rerun set,
waiting for the next run event) or fix_error (fix runner failed, next retry
scheduled) → after the retry delays are exhausted: done or exhausted.
exhausted chains have a GitHub issue opened.
Development
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytestLicense
Available Tools
8 toolscreate_issue_nowCreate Issue NowB
Create a GitHub issue for a chain (requires GitHub client).
Inputs: chain_id (required). Returns: object
get_chainGet ChainA
Get a single chain by ID, or error if not found.
Inputs: chain_id (required). Returns: object
healthHealthA
Health check with DB status and chain counts.
Inputs: no named parameters. Returns: object
list_chainsList ChainsB
List fix-and-retry chains, optionally filtered by state.
Inputs: state. Returns: result
pause_chainPause ChainA
Pause a chain (only if running, waiting, or fix_error).
Inputs: chain_id (required). Returns: object
resume_chainResume ChainB
Resume a paused chain.
Inputs: chain_id (required). Returns: object
retry_nowRetry NowC
Schedule a chain for immediate retry.
Inputs: chain_id (required). Returns: object
set_configSet ConfigA
Set a configuration override (gh_oc_auto or retry_delays_min).
Inputs: key (required), value (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct action or resource: listing/getting chains, retrying, pausing/resuming, creating issues, config, and health. There is minor potential confusion between retry_now and resume_chain since both make a chain active again, but the descriptions clarify the difference. Overall, boundaries are clear.
Most tools follow a verb_noun pattern: list_chains, get_chain, pause_chain, resume_chain, set_config. Minor deviations include health (bare noun) and create_issue_now (verb_noun_adverb), but these are still readable and do not break the overall convention.
Eight tools is a well-scoped set for a fix-and-retry workflow server. Each tool covers a necessary operational aspect: inspection, state changes, issue creation, configuration, and health monitoring. No tool feels redundant or extraneous.
The tool surface covers the core lifecycle of chains: list, get, retry, pause, resume, plus config and health. A delete/cancel operation is missing, but it may not be needed for this domain. Minor gap, but agents can generally operate without dead ends.
Maintenance
Related MCP Connectors
MCP-native AI SRE: ask what's broken in production, get a reviewed GitHub fix PR.
Open-source Zapier/n8n alternative as an MCP server: agents build, run and debug your workflows.
Automate fixes for failed Vercel deploys and cron jobs: sends the cause to your coding agent.
AI code review for GitHub PRs with an MCP autofix loop for Claude Code and Cursor
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that diagnoses GitHub Actions workflow failures and automatically creates repair pull requests using LLM-generated unified diffs. It includes a governance layer to orchestrate autonomous fixes or human-reviewed repairs based on risk assessment thresholds.-
- AlicenseAqualityDmaintenanceMCP server that spawns autonomous Claude Code agents in GitHub repos, enabling task delegation with persistent state, multi-step workflows, and job monitoring.4729 npm2Apache 2.0
- AlicenseAqualityDmaintenanceAn intelligent MCP server that gives AI agents full control over GitHub Actions CI/CD pipelines, including real-time monitoring, log analysis, AI-powered failure diagnosis, and deployment management.13497 npm1ISC
- AlicenseNot gradedqualityDmaintenanceMCP server that pushes GitHub Actions CI/CD results and PR events into Claude Code sessions, enabling automatic investigation and remediation.42 npm1MIT