🤖 Co-authored with Claude Code - Building workflows so LLMs can finally follow a recipe without burning the kitchen! 🔥

A powerful Model Context Protocol (MCP) implementation that enables LLMs to execute complex, multi-step workflows with cognitive actions and tool integrations.

workflows-mcp transforms how AI assistants handle complex tasks by providing structured, reusable workflows that combine tool usage with cognitive reasoning. Instead of ad-hoc task execution, workflows provide deterministic, reproducible paths through multi-step processes.

• 📋 Structured Workflows: Define clear, step-by-step instructions for LLMs
• 🧠 Cognitive Actions: Beyond tool calls - analyze, consider, validate, and reason
• 🔀 Advanced Control Flow: Branching, loops, parallel execution
• 💾 State Management: Track variables and results across workflow steps
• 🔍 Comprehensive Validation: Ensure workflow integrity before execution
• 📊 Execution Tracking: Monitor success rates and performance metrics
• 🛡️ Type-Safe: Full TypeScript support with Zod validation
• 🎯 Dependency Management: Control variable visibility to reduce token usage
• ⚡ Performance Optimized: Differential updates and progressive step loading

npx @fiveohhwon/workflows-mcp

npm install -g @fiveohhwon/workflows-mcp

git clone https://github.com/FiveOhhWon/workflows-mcp.git cd workflows-mcp npm install npm run build

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "workflows": { "command": "npx", "args": ["-y", "@fiveohhwon/workflows-mcp"] } } }

{ "mcpServers": { "workflows": { "command": "workflows-mcp" } } }

{ "mcpServers": { "workflows": { "command": "node", "args": ["/absolute/path/to/workflows-mcp/dist/index.js"] } } }

For development with hot reload:

npm run dev

Workflows are JSON documents that define a series of steps for an LLM to execute:

{ "name": "Code Review Workflow", "description": "Automated code review with actionable feedback", "goal": "Perform comprehensive code review", "version": "1.0.0", "inputs": { "file_path": { "type": "string", "description": "Path to code file", "required": true } }, "steps": [ { "id": 1, "action": "tool_call", "tool_name": "read_file", "parameters": {"path": "{{file_path}}"}, "save_result_as": "code_content" }, { "id": 2, "action": "analyze", "description": "Analyze code quality", "input_from": ["code_content"], "save_result_as": "analysis" } ] }

• tool_call: Execute a specific tool with parameters

• analyze: Examine data and identify patterns
• consider: Evaluate options before deciding
• research: Gather information from sources
• validate: Check conditions or data integrity
• summarize: Condense information to key points
• decide: Make choices based on criteria
• extract: Pull specific information from content
• compose: Generate new content

• branch: Conditional execution paths
• loop: Iterate over items or conditions
• parallel: Execute multiple steps simultaneously
• wait_for_input: Pause for user input

• transform: Convert data formats
• checkpoint: Save workflow state
• notify: Send updates
• assert: Ensure conditions are met
• retry: Attempt previous step again

1. create_workflow - Create a new workflow

   { "workflow": { "name": "My Workflow", "description": "What it does", "goal": "Desired outcome", "steps": [...] } }

2. list_workflows - List all workflows with filtering

   { "filter": { "tags": ["automation"], "name_contains": "review" }, "sort": { "field": "created_at", "order": "desc" } }

3. get_workflow - Retrieve a specific workflow

   { "id": "workflow-uuid" }

4. update_workflow - Modify existing workflow

   { "id": "workflow-uuid", "updates": { "description": "Updated description" }, "increment_version": true }

5. delete_workflow - Soft delete (recoverable)

   { "id": "workflow-uuid" }

6. start_workflow - Start a workflow execution session

   { "id": "workflow-uuid", "inputs": { "param1": "value1" } }

   Returns execution instructions for the first step and an execution_id.

7. run_workflow_step - Execute the next step in the workflow

   { "execution_id": "execution-uuid", "step_result": "result from previous step", "next_step_needed": true }

   Call this after completing each step to proceed through the workflow.

8. get_workflow_versions - List all available versions of a workflow

   { "workflow_id": "workflow-uuid" }

   Returns list of all saved versions for version history tracking.

9. rollback_workflow - Rollback a workflow to a previous version

   { "workflow_id": "workflow-uuid", "target_version": "1.0.0", "reason": "Reverting breaking changes" }

   Restores a previous version as the active workflow.

The workflow system supports interactive, step-by-step execution similar to the sequential thinking tool:

1. Start a workflow with start_workflow - returns the first step instructions
2. Execute the step following the provided instructions
3. Continue to next step with run_workflow_step, passing:
   • The execution_id from start_workflow
   • Any step_result from the current step
   • next_step_needed: true to continue (or false to end early)
4. Repeat until the workflow completes

Each step provides:

• Clear instructions for what to do
• Current variable state
• Expected output format
• Next step guidance

The workflow system supports template variable substitution using {{variable}} syntax:

• In parameters: "path": "output_{{format}}.txt" → "path": "output_csv.txt"
• In descriptions: "Processing {{count}} records" → "Processing 100 records"
• In prompts: "Enter value for {{field}}" → "Enter value for email"
• In transformations: Variables are automatically substituted

Template variables are resolved from the current workflow session variables, including:

• Initial inputs provided to start_workflow
• Results saved from previous steps via save_result_as
• Any variables set during workflow execution

The workflow system includes advanced features to minimize token usage and improve performance for complex workflows:

Control which variables are visible to each step to dramatically reduce context size:

{ "name": "Optimized Workflow", "strict_dependencies": true, // Enable strict mode "steps": [ { "id": 1, "action": "tool_call", "tool_name": "read_large_file", "save_result_as": "large_data" }, { "id": 2, "action": "analyze", "input_from": ["large_data"], "save_result_as": "summary", "dependencies": [] // In strict mode, sees NO previous variables }, { "id": 3, "action": "compose", "dependencies": [2], // Only sees 'summary' from step 2 "save_result_as": "report" }, { "id": 4, "action": "validate", "show_all_variables": true, // Override to see everything "save_result_as": "validation" } ] }

• strict_dependencies (boolean, default: false)
  • false: Steps without dependencies see all variables (backward compatible)
  • true: Steps without dependencies see NO variables (must explicitly declare)

• dependencies (array of step IDs)

  • Lists which previous steps' outputs this step needs
  • Step only sees outputs from listed steps plus workflow inputs
  • Empty array in strict mode means NO variables visible

• show_all_variables (boolean)

  • Override for specific steps that need full visibility
  • Useful for validation or debugging steps

1. Differential State Updates: Only shows variables that changed

   • + variable_name: Newly added variables
   • ~ variable_name: Modified variables
   • Unchanged variables are not displayed

2. Progressive Step Loading: Only shows next 3 upcoming steps

   • Reduces context for long workflows
   • Shows "... and X more steps" for remaining

3. Selective Variable Display: Based on dependencies

   • Dramatically reduces tokens for workflows with verbose outputs
   • Maintains full state internally for branching/retry

1. Use strict_dependencies: true for workflows with large intermediate outputs
2. Explicitly declare dependencies to minimize variable visibility
3. Place verbose outputs early in the workflow and filter them out in later steps
4. Use meaningful variable names to make dependencies clear
5. Group related steps to minimize cross-dependencies

{ "name": "Large Data Processing", "strict_dependencies": true, "inputs": { "file_path": { "type": "string", "required": true } }, "steps": [ { "id": 1, "action": "tool_call", "tool_name": "read_csv", "parameters": { "path": "{{file_path}}" }, "save_result_as": "raw_data" }, { "id": 2, "action": "transform", "transformation": "Extract key metrics only", "dependencies": [1], // Only sees raw_data "save_result_as": "metrics" }, { "id": 3, "action": "analyze", "criteria": "Identify trends and anomalies", "dependencies": [2], // Only sees metrics, not raw_data "save_result_as": "analysis" }, { "id": 4, "action": "compose", "criteria": "Create executive summary", "dependencies": [2, 3], // Sees metrics and analysis only "save_result_as": "report" } ] }

In this example:

• Step 2 processes large raw data but only outputs key metrics
• Step 3 analyzes metrics without seeing the large raw data
• Step 4 creates a report from metrics and analysis only
• Token usage is minimized by filtering out verbose intermediate data

Analyzes code quality, identifies issues, and provides improvement suggestions.

• Sample data: /workflows/examples/sample-data/sample-code-for-review.js

ETL workflow with validation, quality checks, and conditional branching.

• Sample data: /workflows/examples/sample-data/sample-data.csv

Gathers information, validates sources, and produces comprehensive reports.

Basic example showing file operations, branching, and transformations.

See the /workflows/examples directory for complete workflow definitions.

You can manually add workflows by placing JSON files in the imports directory:

1. Navigate to ~/.workflows-mcp/imports/
2. Place your workflow JSON files there (any filename ending in .json)
3. Start or restart the MCP server
4. The workflows will be automatically imported with:
   • A new UUID assigned if missing or invalid
   • Metadata created if not present
   • Original files moved to imports/processed/ after successful import

Example workflow file structure:

{ "name": "My Custom Workflow", "description": "A manually created workflow", "goal": "Accomplish something specific", "version": "1.0.0", "steps": [ { "id": 1, "action": "tool_call", "description": "First step", "tool_name": "example_tool", "parameters": {} } ] }

workflows-mcp/ ├── src/ │ ├── types/ # TypeScript interfaces and schemas │ ├── services/ # Core services (storage, validation) │ ├── utils/ # Utility functions │ └── index.ts # MCP server implementation ├── workflows/ │ └── examples/ # Example workflows │ └── sample-data/ # Sample data files for testing └── tests/ # Test suite 

# Install dependencies npm install # Run in development mode npm run dev # Build for production npm run build # Run tests npm test # Type checking npm run typecheck

• ⚡ Added dependency-based variable filtering for token optimization
• ✨ Added strict_dependencies workflow flag for explicit variable control
• ✨ Added dependencies array to steps for selective variable visibility
• ✨ Added show_all_variables step override for full visibility when needed
• 🎯 Implemented differential state updates (shows only changed variables)
• 📊 Added progressive step loading (shows only next 3 steps)
• 🐛 Fixed UUID validation error in update_workflow tool
• 📝 Added explicit instructions to prevent commentary during workflow execution

• ✨ Added workflow versioning with automatic version history
• ✨ Added get_workflow_versions tool to list all versions
• ✨ Added rollback_workflow tool to restore previous versions
• 📁 Version history stored in ~/.workflows-mcp/versions/

• ✨ Added template variable resolution ({{variable}} syntax)
• ✨ Fixed branching logic to properly handle conditional steps
• ✨ Enhanced create_workflow tool with comprehensive embedded documentation
• 🐛 Fixed ES module import issues
• 📁 Improved file organization with sample-data folder

• ✨ Implemented step-by-step workflow execution
• ✨ Added start_workflow and run_workflow_step tools
• ✨ Session management for workflow state
• 🔄 Replaced run_workflow with interactive execution

• 🎉 Initial release
• ✨ Core workflow engine
• ✨ 16 action types
• ✨ Import/export functionality
• ✨ Example workflows

• Core workflow engine
• Basic action types
• Workflow validation
• Example workflows
• Step-by-step execution
• Variable interpolation
• Branching logic
• Import/export system
• Advanced error handling and retry logic
• Loop and parallel execution
• Workflow marketplace
• Visual workflow builder
• Performance optimizations
• Workflow versioning and rollback

We welcome contributions! Please see our Contributing Guidelines for details.

This project is licensed under the MIT License - see the LICENSE file for details.

Built on the Model Context Protocol specification by Anthropic.