@global-packages/runbook-mcp

Universal AI-powered Incident Runbook Automation MCP Server

Connect your runbooks from GitHub, Azure DevOps, Confluence, Notion, and local filesystem — let AI agents guide step-by-step incident response with human approval gates and automatic post-mortem generation.

🚀 Install

# Global install
npm install -g @global-packages/runbook-mcp

# Or run instantly with npx (no install needed)
npx @global-packages/runbook-mcp

✨ What It Does

• 🔍 Searches your runbooks across GitHub, Azure DevOps, Confluence, Notion, and local filesystem
• 🤖 Guides AI agents step-by-step through incident response using MCP protocol
• 🛡️ Enforces human approval gates on dangerous steps (restart, delete, kill, rollback, etc.)
• 📝 Auto-generates post-mortem documents with full timeline, steps executed, and action items
• 💾 Persists sessions to disk — survive restarts without losing state
• 🔑 Per-source authentication — each source has its own token, zero coupling

⚡ Quick Start

1. GitHub-only (minimum config)

# Set environment variables
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
export GITHUB_REPO=my-org/runbooks
export GITHUB_RUNBOOK_PATH=runbooks/

# Run
npx @global-packages/runbook-mcp

2. Multi-source (config file)

# Copy the example config
cp runbook-mcp.config.example.json runbook-mcp.config.json

# Edit with your sources and tokens
vim runbook-mcp.config.json

# Run
npx @global-packages/runbook-mcp

3. MCP Client Config (Claude Desktop)

{
  "mcpServers": {
    "runbook-mcp": {
      "command": "npx",
      "args": ["-y", "@global-packages/runbook-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
        "GITHUB_REPO": "my-org/runbooks",
        "GITHUB_RUNBOOK_PATH": "runbooks/"
      }
    }
  }
}

🛠️ Tools Exposed (8 Total)

| # | Tool | Description | |---|------|-------------| | 1 | search_runbooks | Search runbooks by incident description or keyword across all sources | | 2 | get_runbook | Get full runbook details including all steps | | 3 | list_runbooks | List all available runbooks (with optional source/tag filters) | | 4 | start_incident_session | Start a new incident response session from a runbook | | 5 | get_next_step | Get the next step to execute in an active session | | 6 | approve_step | Approve a dangerous step requiring human confirmation | | 7 | complete_step | Mark a step as completed and record the result | | 8 | generate_postmortem | Generate a structured post-mortem document |

📡 Supported Sources

| Source | API | Auth | |--------|-----|------| | GitHub | REST API v3 | Personal Access Token | | Azure DevOps | Wiki REST API 7.1 | Personal Access Token | | Confluence | Cloud REST API v1 | Basic (email:api_token) | | Notion | API 2022-06-28 | Integration Secret | | Filesystem | Local fs | None |

📋 Multi-Source Config

Create a runbook-mcp.config.json in your working directory or at ~/.runbook-mcp/config.json:

{
  "sources": [
    {
      "type": "github",
      "name": "My GitHub Org",
      "repo": "my-org/runbooks",
      "path": "runbooks/",
      "branch": "main",
      "token": "ghp_xxxxxxxxxxxx"
    },
    {
      "type": "azuredevops",
      "name": "My ADO Wiki",
      "org": "my-org",
      "project": "my-project",
      "wiki": "my-project.wiki",
      "path": "/Runbooks",
      "token": "ADO_PAT_xxxxxxxxxxxx"
    },
    {
      "type": "confluence",
      "name": "My Confluence",
      "baseUrl": "https://mycompany.atlassian.net",
      "spaceKey": "OPS",
      "labelFilter": "runbook",
      "token": "base64_email:api_token_here"
    },
    {
      "type": "notion",
      "name": "My Notion",
      "databaseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "token": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    {
      "type": "filesystem",
      "name": "Local Runbooks",
      "path": "/opt/runbooks",
      "extension": ".md"
    }
  ],
  "approvalGates": true,
  "postMortemTemplate": "default",
  "sessionStoragePath": "~/.runbook-mcp/sessions"
}

Config Resolution Priority

1. RUNBOOK_MCP_CONFIG env var → path to JSON file
2. ./runbook-mcp.config.json in current working directory
3. ~/.runbook-mcp/config.json in home directory
4. Pure environment variable fallback (for single-source quick start)

🔐 Environment Variables

For quick-start without a config file:

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITHUB_REPO=my-org/runbooks
GITHUB_RUNBOOK_PATH=runbooks/

# Azure DevOps
ADO_TOKEN=your_ado_pat
ADO_ORG=my-org
ADO_PROJECT=my-project
ADO_WIKI=my-project.wiki
ADO_WIKI_PATH=/Runbooks

# Confluence
CONFLUENCE_URL=https://mycompany.atlassian.net
CONFLUENCE_SPACE=OPS
CONFLUENCE_TOKEN=base64token

# Notion
NOTION_TOKEN=secret_xxx
NOTION_DATABASE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Filesystem
FILESYSTEM_PATH=/opt/runbooks

# Options
APPROVAL_GATES=true
SESSION_STORAGE_PATH=~/.runbook-mcp/sessions

🛡️ Approval Gates

Steps containing dangerous keywords are automatically flagged:

restart, delete, drop, kill, failover, rollback, reboot, terminate, disable, flush, drain, purge, destroy, shutdown, force, remove, truncate, wipe

When approvalGates: true (default):

1. The AI agent will pause at dangerous steps
2. A human must explicitly approve using the approve_step tool
3. Only after approval can the step proceed

📄 Runbook Format

Runbooks should be written in Markdown. The parser detects:

# Database Failover Runbook

tags: database, failover, p1

## Step 1: Check database connectivity
Run the health check to verify current state.

```bash
pg_isready -h primary-db.internal -p 5432

Expected: Connection should be established

Step 2: Initiate failover

⚠️ This will restart the primary database.

kubectl exec -it postgres-0 -- pg_ctl promote -D /data

Expected: Standby promoted to primary

Step 3: Verify failover success

Confirm the new primary is accepting writes.

psql -h primary-db.internal -c "SELECT pg_is_in_recovery();"

Expected: Returns 'f' (false = primary mode)

## 📊 Post-Mortem Generation

After completing an incident session, generate a structured post-mortem:

Use the generate_postmortem tool with sessionId="" and resolveSession=true

The generated post-mortem includes:
- **Summary** — incident ID, duration, severity, affected services
- **Alert Context** — source, trigger time, original alert details
- **Timeline** — every action taken with timestamps and results
- **Steps Executed** — detailed results for each completed step
- **Steps Skipped** — any steps not executed
- **Root Cause Analysis** — TODO placeholder
- **Action Items** — checklist for follow-up
- **Lessons Learned** — TODO placeholder

## 🏗️ Development

```bash
# Clone the repo
git clone https://github.com/global-packages/runbook-mcp.git
cd runbook-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Run tests
npm test

📦 Publishing

npm login
npm version patch  # or minor / major
npm run build
npm publish --access public

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a Pull Request

📜 License

MIT — see LICENSE for details.

🔗 Links

• npm: https://www.npmjs.com/package/@global-packages/runbook-mcp
• GitHub: https://github.com/global-packages/runbook-mcp
• MCP Protocol: https://modelcontextprotocol.io

Built with ❤️ by global-packages