# workflows-mcp-server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/cyanheads/workflows-mcp-server  
**GitHub Stars:** 32  
**npm Downloads (last month):** 1156  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/workflows-mcp-server

## Description
Store, query, and create YAML workflow playbooks for LLM agents.

## Tools
Capabilities this server exposes over MCP:

- **workflow_list** — List permanent workflows, optionally narrowed by category (case-insensitive substring), tags (AND match), and a keyword query matched against workflow names and descriptions. Filters combine with AND. Set includeTools to true to surface the unique <server>/<tool> pairs used across each matching workflow. Temporary workflows are never included.
- **workflow_get** — Retrieve a complete workflow definition by name. When version is omitted, returns the highest available version. Also returns optional global execution guidance to apply when running the workflow, or null when none is configured. Template placeholders like {{input.foo}} in step params are opaque strings, returned verbatim. Temporary workflows are accessible here but excluded from workflow_list.
- **workflow_create** — Create and durably store a new permanent workflow. Rejects the write when the same name and version already exist, as a permanent workflow or a temporary draft — bump the version to store a revision alongside the existing one. Created and last-updated dates are stamped automatically. Template placeholders like {{input.foo}} in step params are stored verbatim, not resolved. New workflows appear in workflow_list and are retrievable with workflow_get.
- **workflow_create_temp** — Create a temporary workflow draft for a one-shot plan, scaffolding, or a draft not yet meant for the permanent library. Drafts are retrievable with workflow_get but never appear in workflow_list. A draft stays on disk until it is deleted with workflow_delete — nothing expires it. Writing a name and version that already has a draft overwrites that draft, keeps its created date, and reports status "overwritten"; a name and version held by a permanent workflow is rejected. Created and last-updated dates are stamped automatically.
- **workflow_delete** — Remove a workflow — a permanent workflow or a temporary draft — from the library by name. When version is omitted, the highest version across both is selected; pass a version to target a specific one. Before anything is deleted, the user is asked to confirm the resolved workflow (name@version, whether it is permanent or temporary, and its file). Each prompt is valid for one answer within 10 minutes, and the file is deleted only if it is unchanged since the user saw it; a declined confirmation deletes nothing, and a client that cannot show the prompt cannot delete. Deletion is irreversible: the file is removed, and the workflow no longer appears in workflow_list or workflow_get — unless another file declares the same name and version, in which case that copy takes its place and the result carries a notice naming it. Deleting a draft frees its name and version for workflow_create.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):

```json
"mcpServers": {
  "workflows-mcp-server": {
    "command": "bunx",
    "args": ["@cyanheads/workflows-mcp-server@latest"],
    "env": {
      "MCP_TRANSPORT_TYPE": "",
      "WORKFLOWS_DIR": "",
      "MCP_HTTP_PORT": ""
    }
  }
}
```

**Requires environment variables:** `MCP_TRANSPORT_TYPE`, `WORKFLOWS_DIR`, `MCP_HTTP_PORT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What workflows-mcp-server does

workflows-mcp-server provides an MCP interface to a local YAML workflow library. Each playbook has a name, semantic version, description, author, category, optional tags, and a sequence of steps that identify MCP server/tool calls. Permanent workflows live in category directories and are available through listing and retrieval operations. Temporary drafts are stored separately for one-shot plans or unfinished work.

The server also returns global execution guidance from `global_instructions.md` with each workflow retrieval. Template expressions such as `{{input.foo}}` remain literal text; the server stores and returns them without resolving their values.

## How it works

Workflow files are validated while the library index is built. Invalid files are skipped and logged rather than stopping the server. A recursive watcher refreshes the in-memory index after file changes, and an `_index.json` snapshot is written after rebuilds. Permanent workflows take precedence when a permanent file and a temporary draft declare the same name and version.

Versions use canonical semantic-version formatting. Leading `v`, surrounding whitespace, and build metadata are removed when keys are stored and looked up. Writes and deletes are serialized so existence checks remain valid through the filesystem operation. The server can run over STDIO or Streamable HTTP and is built on `@cyanheads/mcp-ts-core`.

## Setup and configuration

The default storage location is a local `workflows-yaml/` directory. Set `WORKFLOWS_DIR` to use another location. A client can launch the package with `bunx` or `npx`; Docker is also supported when the workflow directory is mounted into the container.

For an HTTP deployment, set `MCP_TRANSPORT_TYPE=http` and choose a port with `MCP_HTTP_PORT`; the MCP endpoint is served at `/mcp`. STDIO configurations set `MCP_TRANSPORT_TYPE=stdio`. No API key is required for the basic local setup.

Claude Desktop, Cursor, and VS Code have installation or configuration paths provided for the package. Example workflows can be used as a starting point, and `global_instructions.md` can define guidance included in every `workflow_get` response.

## Tools and capabilities

- `workflow_list` searches permanent workflows by name or description, category substring, and tags. Filters combine with AND logic. An `includeTools` option adds unique `server/tool` pairs used by each result.
- `workflow_get` returns the complete definition for a requested name and optional version. Omitting the version selects the highest available version, including temporary drafts.
- `workflow_create` writes a new permanent workflow and stamps creation and update dates. Existing name/version keys are rejected.
- `workflow_create_temp` writes a draft outside list results. Reusing an existing draft key replaces that draft while preserving its creation date.
- `workflow_delete` removes a permanent workflow or draft after client confirmation. The confirmation identifies the resolved key, source, and file, and is valid for one response within ten minutes.

Responses include whether a retrieved workflow is permanent or temporary, while failures use typed reason codes such as `not_found`, `already_exists`, `cancelled`, and `target_changed`.

## Limitations and notes

Temporary drafts do not expire automatically and remain on disk until deleted. They cannot be returned by `workflow_list`, although `workflow_get` can retrieve them. Workflow deletion is irreversible, requires a client capable of showing the confirmation prompt, and is refused if the target file changes after confirmation. Name/version collisions are rejected for permanent creation, while a temporary creation can overwrite only a draft with the same key. Workflow steps are not executed by this server, and template placeholders are not interpolated.

_Full upstream README: https://allmcps.com/mcp/workflows-mcp-server/readme_