runbook

The Runbook MCP Server enables you to execute your own runbooks from Claude Desktop. It accepts runbooks defined in Markdown or text files and supports environment variable substitution, so you can customize behavior based on your deployment. The server exposes a get_runbook_as_prompt capability that Claude Desktop can call to fetch a runbook prompt and run it across connected MCP servers (e.g., Kubernetes, GitHub, Slack, web tools). To start using it, configure Claude Desktop to point to the Runbook MCP under the mcpServers section, then create or import runbooks and corresponding env.yaml definitions. You can also create new runbooks using the create_runbook tool and pass a name and content for automatic processing. When executing a runbook, you select the runbook by name from Claude Desktop, optionally supply variables (as key=value pairs), and submit the generated prompt to trigger the sequence across the connected MCP servers.

Prerequisites:

• Python 3.8+ installed on the host where you run the MCP server
• Claude Desktop installed for integration
• Access to the Runbook MCP directory structure (local runbooks directory)

1. Prepare your environment

• Ensure Python is installed and available in PATH
• Create the runbook server directory, e.g. /path/to/runbook-mcp-server
• Place your runbook files (Markdown or text) in the directory

2. Install dependencies (if any)

• If a virtual environment is used, create and activate it: python -m venv venv source venv/bin/activate # on Linux/macOS venv\Scripts\activate # on Windows
• Install required Python packages (if a requirements.txt is provided): pip install -r requirements.txt

3. Configure Claude Desktop to run the MCP server

• Create a configuration file at claude_desktop_config.json with the following structure (adjust paths as needed): { "mcpServers": { "runbook": { "command": "uv", "args": [ "--directory", "<ABSOLUTE_PATH>/runbook-mcp-server", "run", "runbook_server.py" ] } } }

4. Run the server

• From the terminal, start the MCP server using the configured command (as defined in claude_desktop_config.json): uv --directory /absolute/path/runbook-mcp-server run runbook_server.py

5. Create and manage runbooks

• Add runbooks in the runbook-mcp-server directory as Markdown or text files
• Define env.yaml for environment variable substitution if needed
• To create new runbooks via the tool, use the create_runbook prompt example provided in the README

6. Run runbooks from Claude Desktop

• In Claude Desktop, choose Attach from MCP, select get_runbook_as_prompt, specify the runbook name, provide variables as var1=value1,var2=value2 if needed, then submit

Tips and common issues:

• Ensure the <ABSOLUTE_PATH> used in the configuration is correct and accessible by the user running the MCP server.
• If environment variables are required by your runbooks, populate env.yaml with the appropriate key:value pairs and verify the substitution rules you defined (e.g., {env[key]}).
• When updating runbooks, rebuild or refresh the index in the Runbook MCP so Claude Desktop can discover changes.
• If using multiple MCP servers, confirm the connect/discovery mechanism in Claude Desktop is configured to communicate with all relevant servers (GitHub, Slack, Kubernetes, etc.).
• For debugging, run the CLI command manually to verify the server starts correctly before integrating with Claude Desktop.