# workflows-mcp-server

Stores, queries, and creates YAML workflow playbooks for LLM agents. Handy for organizing reusable multi-step tool execution sequences across sessions.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 31
- Author: cyanheads
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cyanheads/workflows-mcp-server
- Updated: 2026-10-07
- HTML: https://affpapa.org/en/nevibecode/mcp/workflows-mcp-server

## What it does

The server exposes local YAML files as an actionable playbook catalog for autonomous agents. It provides five tools: `workflow_list`, `workflow_get`, `workflow_create`, `workflow_create_temp`, and `workflow_delete`. Permanent routines reside in categorized subdirectories, whereas temporary drafts go into `temp/` and remain hidden from general search results.

An in-memory index rebuilds automatically whenever files change on disk. Every playbook is tracked by a canonical semver key combining name and version. The server never interpolates template variables like `{{input.foo}}`, sending placeholders back untouched for the calling agent to parse.

Deleting any record requires interactive user elicitation. If an MCP client cannot prompt the human for confirmation, `workflow_delete` simply fails to prevent unintended data loss.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `WORKFLOWS_DIR`, `GLOBAL_INSTRUCTIONS_PATH`, `WATCHER_DEBOUNCE_MS`, `MCP_LOG_LEVEL`, `MCP_TRANSPORT_TYPE`, `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, `MCP_HTTP_ENDPOINT_PATH`, `MCP_AUTH_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env WORKFLOWS_DIR=<WORKFLOWS_DIR> --env GLOBAL_INSTRUCTIONS_PATH=<GLOBAL_INSTRUCTIONS_PATH> --env WATCHER_DEBOUNCE_MS=<WATCHER_DEBOUNCE_MS> --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --transport stdio workflows-mcp-server -- npx -y @cyanheads/workflows-mcp-server
```
Replace <…> with your own values. 4 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add workflows-mcp-server --env WORKFLOWS_DIR=<WORKFLOWS_DIR> --env GLOBAL_INSTRUCTIONS_PATH=<GLOBAL_INSTRUCTIONS_PATH> --env WATCHER_DEBOUNCE_MS=<WATCHER_DEBOUNCE_MS> --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> -- npx -y @cyanheads/workflows-mcp-server
```
Replace <…> with your own values. 4 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "workflows-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@cyanheads/workflows-mcp-server"
            ],
            "env": {
                "WORKFLOWS_DIR": "<WORKFLOWS_DIR>",
                "GLOBAL_INSTRUCTIONS_PATH": "<GLOBAL_INSTRUCTIONS_PATH>",
                "WATCHER_DEBOUNCE_MS": "<WATCHER_DEBOUNCE_MS>",
                "MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
                "MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>"
            }
        }
    }
}
```
Replace <…> with your own values. 4 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "workflows-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@cyanheads/workflows-mcp-server"
            ],
            "env": {
                "WORKFLOWS_DIR": "<WORKFLOWS_DIR>",
                "GLOBAL_INSTRUCTIONS_PATH": "<GLOBAL_INSTRUCTIONS_PATH>",
                "WATCHER_DEBOUNCE_MS": "<WATCHER_DEBOUNCE_MS>",
                "MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
                "MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>"
            }
        }
    }
}
```
Replace <…> with your own values. 4 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e WORKFLOWS_DIR=<WORKFLOWS_DIR> -e GLOBAL_INSTRUCTIONS_PATH=<GLOBAL_INSTRUCTIONS_PATH> -e WATCHER_DEBOUNCE_MS=<WATCHER_DEBOUNCE_MS> -e MCP_LOG_LEVEL=<MCP_LOG_LEVEL> -e MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> workflows-mcp-server npx -y @cyanheads/workflows-mcp-server
```
Replace <…> with your own values. 4 more environment variables are in the server README

## When to use it
- store recurring tool execution sequences as versioned YAML playbooks
- filter permanent agent workflows by keywords, categories, and tags
- draft temporary action playbooks without cluttering public listings
- retrieve full procedure steps with prepended global instructions

## Example prompts
- Find all workflows tagged with devops using `workflow_list`.
- Retrieve the latest playbook for release verification via `workflow_get`.
- Draft a temporary action playbook using `workflow_create_temp`.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md