Workflows MCP server

workflows-mcp is a powerful Model Context Protocol (MCP) implementation that enables large language models to execute complex, multi-step workflows combining tool usage with cognitive reasoning. Instead of ad-hoc task execution, it provides structured, reusable workflows for deterministic and reproducible processes.

Installation

Using npx (Recommended)

npx @fiveohhwon/workflows-mcp

From npm

npm install -g @fiveohhwon/workflows-mcp

From Source

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

Configuration

Claude Desktop Setup

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

Using npx (recommended):

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

Using global install:

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

Using local build:

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

Workflow Structure

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"
    }
  ]
}

Action Types

Tool Actions

• tool_call: Execute a specific tool with parameters

Cognitive Actions

• 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

Control Flow

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

Utility Actions

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

Available Tools

Workflow Management

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"
     }
   }
   

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
   }
   

8. get_workflow_versions - List all available versions of a workflow

   {
     "workflow_id": "workflow-uuid"
   }
   

9. rollback_workflow - Rollback a workflow to a previous version

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

Step-by-Step Execution

The workflow system supports interactive, step-by-step execution:

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

Template Variables

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

Dependency Management & Performance Optimization

Dependency-Based Variable Filtering

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

{
  "name": "Optimized Workflow",
  "strict_dependencies": true,  
  "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": []  
    },
    {
      "id": 3,
      "action": "compose",
      "dependencies": [2],  
      "save_result_as": "report"
    },
    {
      "id": 4,
      "action": "validate",
      "show_all_variables": true,  
      "save_result_as": "validation"
    }
  ]
}

Workflow-Level Settings

• strict_dependencies (boolean, default: false)
  • false: Steps without dependencies see all variables
  • true: Steps without dependencies see NO variables

Step-Level Settings

• dependencies (array of step IDs)

  • Lists which previous steps' outputs this step needs
  • Step only sees outputs from listed steps plus workflow inputs

• show_all_variables (boolean)

  • Override for specific steps that need full visibility

Performance Features

1. Differential State Updates: Only shows variables that changed
2. Progressive Step Loading: Only shows next 3 upcoming steps
3. Selective Variable Display: Based on dependencies

Manual Workflow Import

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

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": {}
    }
  ]
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "workflows" '{"command":"npx","args":["-y","@fiveohhwon/workflows-mcp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect