workflows-mcp-server
Allows storing workflow data using Cloudflare's KV, R2, or D1 storage services.
Allows storing workflow data in a Supabase database, leveraging their Postgres backend for persistence.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Overview
A declarative workflow library for LLM agents, backed by local YAML files. Store, list, and retrieve named, versioned multi-step playbooks — each a sequence of MCP server/tool calls — for permanent reuse or one-shot temporary runs. Edits to the YAML files are picked up automatically.
Tools
Tool | Description |
| List all permanent workflows in the index, with optional keyword, category, and tag filters. |
| Retrieve a complete workflow definition by name, with the library's global instructions included. |
| Write a new permanent workflow YAML to the library. |
| Write a temporary workflow draft, indexed but excluded from list results, kept until deleted. |
| Remove a permanent workflow or a temporary draft by name and optional version, after the user confirms the resolved target. |
Related MCP server: task-graph-mcp
Capability reference
workflow_list tool
Optional
query(name and description),category(substring), andtags(all must match) filters, case-insensitive; temporary drafts are never listedSorted by name, then highest version first; an empty result carries a
noticeechoing the applied filtersincludeTools: trueadds each workflow's uniqueserver/toolpairs
workflow_get tool
nameplus an optional semverversion; omitversionfor the highest available, drafts includedReturns the full workflow, its
source(permanentortemp), andglobalInstructionsfromglobal_instructions.md(nullwhen absent); fails withnot_foundorversion_not_foundTemplate placeholders such as
{{input.foo}}come back verbatim — the server never interpolates them
workflow_create tool
name, semverversion,description,author,category, andsteps(plus optionaltags); stored as one file pername@versionundercategories/<category>/, with created and updated dates stampedReturns the
key(name@version) andfilePath; fails withalready_existswhen a permanent workflow or a draft holds the key,invalid_input, orwrite_failed
workflow_create_temp tool
The
workflow_createfields minuscategory; stored undertemp/, retrievable withworkflow_get, never listed, and kept untilworkflow_deleteremoves itstatusiscreated, oroverwrittenwhen it replaced the draft of the same key (keeping that draft'screated_date); a key held by a permanent workflow fails withalready_exists
workflow_delete tool
nameplus an optionalversion(omitted: the highest across permanent workflows and drafts); the user confirms the resolvedname@version, source, and file before anything is deleted, so a client without elicitation cannot deleteReturns the deleted workflow's
source, plus anoticewhen another file declaring the same key now takes its place; fails withcancelled,confirmation_invalid(a prompt never issued, already answered, older than 10 minutes, or issued to another caller),target_changed(the file or its content changed after the user saw it), ornot_found
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Workflow library:
YAML files under
categories/andtemp/are validated at index time; an invalid file is skipped and logged, never crashes the serverIn-memory index keyed by
name@version, read from each file's content rather than its name and kept fresh by a debounced recursive watcher; a permanent workflow outranks a draft with the same keyVersions are canonical semver everywhere: a leading
v, surrounding whitespace, and build metadata are dropped, sov1.0.0+build.5is stored, keyed, and looked up as1.0.0Creates and deletes run one at a time, so each existence check holds until its write lands; filenames carry a hash of
name@version, so keys whose slugs coincide never share a fileAn
_index.jsonsnapshot is written on every rebuild for external tooling and debugging
Agent-friendly output:
Discriminated output —
source: "permanent" | "temp"on everyworkflow_getresponse and typedreasoncodes (not_found,version_not_found,already_exists,cancelled,confirmation_invalid,target_changed,index_unavailable, …) on failures, so callers branch on data instead of parsing error stringsNo extra round trip —
workflow_getalways returnsglobalInstructionsalongside the workflow definition in the same responseResponse shaping —
workflow_list's optionalincludeToolsflag pre-derives the uniqueserver/toolpairs used by a workflow, and an empty result echoes the applied filters with a broadening hint instead of returning nothing
Getting started
No API keys required. The server reads from a local workflows-yaml/ directory by default.
Add the following to your MCP client configuration file:
{
"mcpServers": {
"workflows-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/workflows-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml"
}
}
}
}Or with npx (no Bun required):
{
"mcpServers": {
"workflows-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/workflows-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"WORKFLOWS_DIR": "/absolute/path/to/your/workflows-yaml"
}
}
}
}Or with Docker:
{
"mcpServers": {
"workflows-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"-v", "/absolute/path/to/your/workflows-yaml:/workflows-yaml",
"-e", "WORKFLOWS_DIR=/workflows-yaml",
"ghcr.io/cyanheads/workflows-mcp-server:latest"
]
}
}
}For Streamable HTTP, set the transport and start the server:
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcpSeed workflows
The repository ships a workflows-yaml/ directory with example workflows organized under categories/. These are ready to use as a starting point. The workflows-yaml/global_instructions.md file contains instructions the server includes in every workflow_get response (the globalInstructions field) — edit it to set global guidance for your agent.
Prerequisites
Bun v1.4.0 or higher (or Node.js v24+).
A local directory containing YAML workflow files (or use the bundled
workflows-yaml/seed).
Installation
Clone the repository:
git clone https://github.com/cyanheads/workflows-mcp-server.gitNavigate into the directory:
cd workflows-mcp-serverInstall dependencies:
bun installConfigure environment:
cp .env.example .env
# edit .env if needed — most settings have defaultsConfiguration
Variable | Description | Default |
| Absolute or relative path to the workflows root directory. |
|
| Path to the global instructions markdown file. Derives from |
|
| Integer milliseconds (0–2147483647) to debounce filesystem change events before rebuilding the index. |
|
| Transport: |
|
| Port for HTTP server. |
|
| HTTP sessions: |
|
| Auth mode: |
|
| Seals the | unset |
| Log level (RFC 5424). |
|
| Log each failed tool call's arguments and result, redacted by key name and capped at |
|
| Enable OpenTelemetry instrumentation (spans, metrics, completion logs). |
|
See .env.example for the full list of optional overrides.
Running the server
Local development
Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:httpRun checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker build -t workflows-mcp-server .
docker run --rm \
-v /path/to/workflows-yaml:/workflows-yaml \
-e WORKFLOWS_DIR=/workflows-yaml \
-p 3010:3010 \
workflows-mcp-serverThe Dockerfile defaults to HTTP transport, stateful session mode (required — see MCP_SESSION_MODE above), and logs to /var/log/workflows-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
|
|
| Unit and integration tests mirroring |
| Seed workflow library — |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped loggingRegister new tools via the barrel in
src/mcp-server/tools/definitions/index.tsFilesystem operations go through
WorkflowIndexService, not directly in tool handlers
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Securely search and manage workspace context files for AI agents and teams.
Build, validate, test-run and publish AIOS workflows from Claude Code, Codex, Cursor or VS Code.
1A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol implementation that enables LLMs to execute complex, multi-step workflows combining tool usage with cognitive reasoning, providing structured, reusable paths through tasks with advanced control flow.927 npm28MIT
- AlicenseNot gradedqualityDmaintenanceProvides structured workflows (phases, gates, coordination) for AI agents, enabling complex task execution with quality enforcement and multi-agent coordination via Model Context Protocol.2Apache 2.0
- FlicenseBqualityDmaintenanceEnables AI assistants to orchestrate multi-step workflows by converting natural language into executable plans, coordinating tools, agents, and services via the Model Context Protocol.4-
- FlicenseNot gradedqualityDmaintenanceEnables AI models to seamlessly integrate with external tools and data sources via the Model Context Protocol, extending functionality without modifying the core model.-