Cron Job Doctor MCP

A remote MCP server that diagnoses scheduled GitHub Actions workflows: finds jobs that have gone silently stuck, are retrying in a loop, are taking progressively longer to run, or just failed on their last run -- and can rerun a specific run or enable/disable a workflow when asked.

Tools exposed:

• list_scheduled_workflows — find every workflow in a repo with a schedule: trigger

• get_workflow_runs — raw run history for one workflow

• diagnose_workflow — run history + anomaly flags (stuck / retry storm / duration creep / recent failure / failure rate), and records a snapshot to history

• get_diagnosis_history — past diagnosis snapshots for a workflow, so you can see trends over time rather than a single point-in-time check

• rerun_workflow — write action: re-runs a specific run (defaults to failed jobs only)

• set_workflow_enabled — write action: enables or disables a workflow's schedule

• diagnose_workflow_widget / compare_workflows_widget — interactive widget versions

1. Prerequisites

• A GitHub account with at least one repo that has a scheduled workflow

• A fine-grained Personal Access Token scoped to the repo(s) you want to check, with:

  • Actions: Read and write (read for diagnostics, write for rerun/enable/disable)

  • Contents: Read and write (read for the schedule check, write for diagnosis history storage)

  • Metadata: Read-only

• A Vercel account

Related MCP server: GitHub Actions MCP

2. Push to GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:<you>/cron-job-doctor-mcp.git
git push -u origin main

3. Import into Vercel

1. Go to vercel.com/new → Import Git Repository → select this repo (install the Vercel GitHub App first if you haven't already)

2. In Environment Variables, add GITHUB_TOKEN with your PAT

3. Click Deploy

4. Diagnosis history storage

get_diagnosis_history and the new-vs-recurring-anomaly diffing store past snapshots as a markdown file (.cron-job-doctor/history/<workflow_id>.md, containing a fenced JSON block) committed to a dedicated cron-job-doctor-history branch in whichever repo is being diagnosed -- not main, and not this server's own repo -- so it doesn't clutter the target repo's regular commit history. The branch is created automatically on first use; no manual setup needed beyond the token scope above.

Every future git push to main on this server's repo auto-deploys.

5. Connect it to Claude / Cowork

Add a custom connector pointing at:

https://<your-vercel-domain>/api/mcp

Then try something like: "Check my repo me/my-project for any cron jobs that need attention."

Local development

npm install
cp .env.example .env.local   # fill in GITHUB_TOKEN
npm run dev