workflows-mcp-server — Claude Code MCP server: setup and overview
Stores, queries, and creates YAML workflow playbooks for LLM agents. Handy for organizing reusable multi-step tool execution sequences across sessions.
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-serverWhat workflows-mcp-server 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.
What it helps with
- 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 for the agent
- 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.
How to install workflows-mcp-server
Platform CLI
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-serverReplace <…> with your own values. 4 more environment variables are in the server README
Platform CLI
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-serverReplace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-serverReplace <…> with your own values. 4 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about workflows-mcp-server
How to install workflows-mcp-server in Claude Code?
Run claude mcp add workflows-mcp-server -- npx -y @cyanheads/workflows-mcp-server in your terminal.
What does workflows-mcp-server do?
It gives agents a structured library of YAML playbooks to list, retrieve, store, and remove multi-step tool execution sequences.
Does the server substitute template variables?
No. Placeholders such as {{input.foo}} are returned untouched, leaving variable resolution to the consuming agent.
