# Workflows Management Tools

Complete reference for all 8 workflow management tools available in the n8n MCP Workflow Builder.

---

## Overview

The workflow management tools enable you to create, read, update, delete, activate, and execute n8n workflows through natural language conversations with Claude AI.

### Tools Summary

| Tool | Purpose | Type | n8n API Endpoint |
|------|---------|------|------------------|
| `list_workflows` | Get all workflows with metadata | Read | `GET /workflows` |
| `get_workflow` | Get complete workflow details | Read | `GET /workflows/{id}` |
| `create_workflow` | Create new workflow | Write | `POST /workflows` |
| `update_workflow` | Modify existing workflow | Write | `PATCH /workflows/{id}` |
| `delete_workflow` | Remove workflow permanently | Write | `DELETE /workflows/{id}` |
| `activate_workflow` | Enable workflow execution | Lifecycle | `PATCH /workflows/{id}` |
| `deactivate_workflow` | Disable workflow execution | Lifecycle | `PATCH /workflows/{id}` |
| `execute_workflow` | Manual execution (guidance) | Execution | N/A (API limitation) |

### Tool Categories

**Read Operations:**
- `list_workflows` - Browse and filter workflows
- `get_workflow` - View detailed workflow configuration

**Write Operations:**
- `create_workflow` - Build new workflows
- `update_workflow` - Modify existing workflows
- `delete_workflow` - Remove workflows

**Lifecycle Operations:**
- `activate_workflow` - Start automatic execution
- `deactivate_workflow` - Stop automatic execution

**Execution Operations:**
- `execute_workflow` - Trigger manual execution (limited by n8n API)

---

## list_workflows

Retrieve a list of all workflows with streamlined metadata.

### Purpose

Get an overview of your workflows without loading full workflow data. Optimized for performance to prevent Claude Desktop from becoming unresponsive with large workflow lists.

### Input Parameters

```typescript
{
  active?: boolean;        // Filter by status
  tags?: string[];         // Filter by tag IDs
  limit?: number;          // Results per page (default: 100, max: 250)
  cursor?: string;         // Pagination cursor
  instance?: string;       // n8n instance identifier (optional)
}
```

### Output Format

```typescript
{
  data: Array<{
    id: string;            // Workflow ID
    name: string;          // Workflow name
    active: boolean;       // Is workflow currently active
    createdAt: string;     // ISO 8601 timestamp
    updatedAt: string;     // ISO 8601 timestamp
    nodes?: number;        // Number of nodes (optional)
    tags?: string[];       // Associated tag IDs (optional)
  }>;
  nextCursor?: string;     // For pagination (if more results exist)
}
```

### Usage Examples

=== "List All Workflows"

    **Request:**
    ```
    List all my n8n workflows
    ```

    **What Claude does:**
    ```typescript
    list_workflows()
    ```

    **Response:**
    ```
    You have 15 workflows:

    1. Email Notification System (ID: 1)
       - Status: Active
       - Created: 2025-12-01
       - Nodes: 5

    2. Data Sync Pipeline (ID: 2)
       - Status: Inactive
       - Created: 2025-12-15
       - Nodes: 8

    [... 13 more workflows ...]
    ```

=== "Filter Active Only"

    **Request:**
    ```
    Show only active workflows
    ```

    **What Claude does:**
    ```typescript
    list_workflows({ active: true })
    ```

    **Response:**
    ```
    You have 8 active workflows:

    1. Email Notification System (ID: 1)
    2. Slack Alert Bot (ID: 5)
    3. Database Backup (ID: 7)
    [... 5 more ...]
    ```

=== "Filter by Tags"

    **Request:**
    ```
    Show workflows tagged with "production"
    ```

    **What Claude does:**
    ```typescript
    // First, get tag ID
    get_tags() // Find "production" tag ID

    // Then filter workflows
    list_workflows({ tags: ["tag_id_123"] })
    ```

=== "Multi-Instance"

    **Request:**
    ```
    List workflows in staging environment
    ```

    **What Claude does:**
    ```typescript
    list_workflows({ instance: "staging" })
    ```

### Performance Notes

!!! info "Optimized for Large Lists"
    - Returns metadata only (not full workflow JSON)
    - 90%+ data reduction compared to full workflow data
    - Prevents Claude Desktop crashes with 100+ workflows
    - Use `get_workflow` for detailed workflow information

### Error Handling

**Common Errors:**

| Error | Cause | Solution |
|-------|-------|----------|
| `401 Unauthorized` | Invalid API key | Verify n8n API key in configuration |
| `404 Not Found` | Wrong API endpoint | Check N8N_HOST URL format |
| `Instance not found` | Invalid instance name | List available instances |
| `Connection refused` | n8n not running | Start n8n instance |

---

## get_workflow

Retrieve complete workflow details including nodes, connections, and settings.

### Purpose

Get full workflow configuration for viewing, editing, or debugging purposes.

### Input Parameters

```typescript
{
  id: string;              // Workflow ID (required)
  instance?: string;       // n8n instance identifier (optional)
}
```

### Output Format

```typescript
{
  id: string;
  name: string;
  active: boolean;
  nodes: Array<{
    id: string;
    name: string;
    type: string;
    typeVersion: number;
    position: [number, number];
    parameters: Record<string, any>;
    credentials?: Record<string, any>;
  }>;
  connections: Record<string, {
    main: Array<Array<{
      node: string;
      type: string;
      index: number;
    }>>;
  }>;
  settings?: Record<string, any>;
  staticData?: Record<string, any>;
  tags?: string[];
  createdAt: string;
  updatedAt: string;
}
```

### Usage Examples

=== "Get by ID"

    **Request:**
    ```
    Show me workflow 15
    ```

    **What Claude does:**
    ```typescript
    get_workflow({ id: "15" })
    ```

    **Response:**
    ```
    Workflow: Email Notification System (ID: 15)
    Status: Active
    Created: 2025-12-01
    Updated: 2025-12-20

    Nodes (5 total):
    1. Schedule Trigger - scheduleTrigger (triggers daily at 9 AM)
    2. Fetch Data - httpRequest (GET request to API)
    3. Transform Data - set (formats email content)
    4. Send Email - email (sends to recipients)
    5. Log Result - set (logs execution status)

    Connections:
    - Schedule Trigger → Fetch Data
    - Fetch Data → Transform Data
    - Transform Data → Send Email
    - Send Email → Log Result
    ```

=== "Multi-Instance"

    **Request:**
    ```
    Get workflow 5 from production
    ```

    **What Claude does:**
    ```typescript
    get_workflow({ id: "5", instance: "production" })
    ```

### Use Cases

- **Debugging:** View workflow configuration to identify issues
- **Documentation:** Generate workflow documentation
- **Cloning:** Copy workflow to create variations
- **Analysis:** Understand workflow structure and dependencies

---

## create_workflow

Create a new n8n workflow with specified configuration.

### Purpose

Build workflows through natural language descriptions. Claude AI generates the necessary nodes, connections, and settings.

### Input Parameters

```typescript
{
  name: string;                    // Workflow name (required)
  nodes: Array<{                   // Workflow nodes (required)
    id: string;
    name: string;
    type: string;
    typeVersion?: number;
    position: [number, number];
    parameters: Record<string, any>;
    credentials?: Record<string, any>;
  }>;
  connections?: Array<{            // Node connections (optional, auto-converted)
    source: string;
    target: string;
    sourceOutput?: number;
    targetInput?: number;
  }>;
  settings?: Record<string, any>;  // Workflow settings (optional)
  staticData?: Record<string, any>; // Static workflow data (optional)
  tags?: string[];                 // Tag IDs (optional)
  instance?: string;               // n8n instance (optional)
}
```

### Output Format

```typescript
{
  id: string;                // New workflow ID
  name: string;
  active: boolean;           // Initially false
  nodes: Array<...>;
  connections: Record<...>;
  createdAt: string;
  updatedAt: string;
}
```

### Usage Examples

=== "Simple Workflow"

    **Request:**
    ```
    Create a workflow called "Daily Backup" that:
    - Runs every day at 2 AM
    - Backs up database
    - Sends completion email
    ```

    **What Claude does:**
    ```typescript
    create_workflow({
      name: "Daily Backup",
      nodes: [
        {
          id: "node1",
          name: "Schedule",
          type: "scheduleTrigger",
          parameters: {
            rule: {
              interval: [{ field: "cronExpression", expression: "0 2 * * *" }]
            }
          },
          position: [250, 300]
        },
        {
          id: "node2",
          name: "Backup Database",
          type: "postgres",
          parameters: {
            operation: "executeQuery",
            query: "SELECT * FROM backup_procedure()"
          },
          position: [450, 300]
        },
        {
          id: "node3",
          name: "Send Email",
          type: "email",
          parameters: {
            toEmail: "admin@example.com",
            subject: "Backup Complete",
            message: "Database backup completed successfully"
          },
          position: [650, 300]
        }
      ],
      connections: [
        { source: "node1", target: "node2" },
        { source: "node2", target: "node3" }
      ]
    })
    ```

=== "Webhook Workflow"

    **Request:**
    ```
    Create a webhook workflow "Order Processor" that receives orders and saves them
    ```

    **What Claude does:**
    ```typescript
    create_workflow({
      name: "Order Processor",
      nodes: [
        {
          id: "webhook",
          name: "Receive Order",
          type: "webhook",
          parameters: {
            path: "process-order",
            responseMode: "lastNode"
          },
          position: [250, 300]
        },
        {
          id: "validate",
          name: "Validate Order",
          type: "code",
          parameters: {
            code: "// Validation logic"
          },
          position: [450, 300]
        },
        {
          id: "save",
          name: "Save to Database",
          type: "postgres",
          parameters: {
            operation: "insert",
            table: "orders"
          },
          position: [650, 300]
        }
      ],
      connections: [
        { source: "webhook", target: "validate" },
        { source: "validate", target: "save" }
      ]
    })
    ```

### Best Practices

!!! tip "Workflow Creation Tips"
    1. **Start simple** - Create minimal workflow, then enhance
    2. **Use descriptive names** - For workflows and nodes
    3. **Test incrementally** - Activate after testing each component
    4. **Position nodes** - Space nodes 200 pixels apart for readability
    5. **Add error handling** - Include error workflow branches

### Validation

The MCP server automatically validates:
- ✅ Required fields presence
- ✅ Node type compatibility
- ✅ Connection validity
- ✅ Parameter formats

---

## update_workflow

Modify an existing workflow configuration.

### Purpose

Update workflow name, nodes, connections, settings, or any other workflow property.

### Input Parameters

```typescript
{
  id: string;                      // Workflow ID (required)
  name?: string;                   // New workflow name
  nodes?: Array<...>;              // Updated nodes array
  connections?: Array<...>;        // Updated connections
  settings?: Record<string, any>;  // Updated settings
  tags?: string[];                 // Updated tag assignments
  instance?: string;               // n8n instance (optional)
}
```

### Output Format

```typescript
{
  id: string;
  name: string;
  active: boolean;
  nodes: Array<...>;
  connections: Record<...>;
  updatedAt: string;              // New update timestamp
}
```

### Usage Examples

=== "Rename Workflow"

    **Request:**
    ```
    Rename workflow 15 to "Daily Email Alerts"
    ```

    **What Claude does:**
    ```typescript
    update_workflow({
      id: "15",
      name: "Daily Email Alerts"
    })
    ```

=== "Update Node Parameters"

    **Request:**
    ```
    Update workflow 10 to send email to new-email@example.com
    ```

    **What Claude does:**
    ```typescript
    // First, get current workflow
    const workflow = get_workflow({ id: "10" })

    // Update email node parameters
    const updatedNodes = workflow.nodes.map(node => {
      if (node.type === "email") {
        return {
          ...node,
          parameters: {
            ...node.parameters,
            toEmail: "new-email@example.com"
          }
        }
      }
      return node
    })

    // Update workflow
    update_workflow({
      id: "10",
      nodes: updatedNodes
    })
    ```

=== "Add New Node"

    **Request:**
    ```
    Add a Slack notification node to workflow 5 after the email node
    ```

    **What Claude does:**
    ```typescript
    // Get current workflow
    const workflow = get_workflow({ id: "5" })

    // Add new node
    const newNode = {
      id: "slack_node",
      name: "Notify Slack",
      type: "slack",
      parameters: {
        channel: "#alerts",
        message: "Task completed"
      },
      position: [850, 300]
    }

    // Add connection
    const newConnection = {
      source: "email_node_id",
      target: "slack_node"
    }

    // Update workflow
    update_workflow({
      id: "5",
      nodes: [...workflow.nodes, newNode],
      connections: [...workflow.connections, newConnection]
    })
    ```

### Important Notes

!!! warning "Full Replacement"
    When updating `nodes` or `connections`, you must provide the **complete** array, not just changes. The update replaces the entire field.

!!! tip "Incremental Updates"
    For complex updates:
    1. Get current workflow with `get_workflow`
    2. Modify the needed properties
    3. Send complete updated configuration

---

## delete_workflow

Permanently remove a workflow and all its execution history.

### Purpose

Delete workflows that are no longer needed. This action is irreversible.

### Input Parameters

```typescript
{
  id: string;              // Workflow ID (required)
  instance?: string;       // n8n instance (optional)
}
```

### Output Format

```typescript
{
  success: boolean;
  message: string;
}
```

### Usage Examples

=== "Delete by ID"

    **Request:**
    ```
    Delete workflow 99
    ```

    **What Claude does:**
    ```typescript
    delete_workflow({ id: "99" })
    ```

    **Response:**
    ```
    ✅ Successfully deleted workflow "Old Test Workflow" (ID: 99)

    The workflow and all its execution history have been permanently removed.
    ```

=== "Delete After Confirmation"

    **Request:**
    ```
    Delete the "Temporary Test" workflow
    ```

    **Claude's response:**
    ```
    I found workflow "Temporary Test" (ID: 42).

    ⚠️ Warning: This action is permanent and will delete:
    - The workflow configuration
    - All execution history
    - All associated data

    Should I proceed with deletion?
    ```

    **User confirms:**
    ```
    Yes, delete it
    ```

    **What Claude does:**
    ```typescript
    delete_workflow({ id: "42" })
    ```

### Safety Considerations

!!! danger "Irreversible Action"
    - **No undo** - Deletion is permanent
    - **History lost** - All execution records deleted
    - **Backup recommended** - Export workflow before deletion if needed

!!! tip "Before Deleting"
    1. **Deactivate first** - Stop executions before deletion
    2. **Export workflow** - Use n8n UI to export if you might need it later
    3. **Check dependencies** - Ensure no other workflows depend on this one
    4. **Verify ID** - Double-check you're deleting the correct workflow

---

## activate_workflow

Enable a workflow for automatic execution based on its triggers.

### Purpose

Start a workflow so it runs automatically when triggered (schedules, webhooks, etc.).

### Input Parameters

```typescript
{
  id: string;              // Workflow ID (required)
  instance?: string;       // n8n instance (optional)
}
```

### Output Format

```typescript
{
  id: string;
  name: string;
  active: boolean;         // Now true
  message?: string;        // Activation details
}
```

### Usage Examples

=== "Basic Activation"

    **Request:**
    ```
    Activate workflow 15
    ```

    **What Claude does:**
    ```typescript
    activate_workflow({ id: "15" })
    ```

    **Response:**
    ```
    ✅ Workflow "Daily Email Report" (ID: 15) has been activated!

    The workflow will now run automatically based on its schedule trigger:
    - Schedule: Every day at 9:00 AM
    - Next execution: 2025-12-28 09:00:00

    Monitor executions with: "Show executions for workflow 15"
    ```

=== "Multi-Instance"

    **Request:**
    ```
    Activate workflow 5 in production
    ```

    **What Claude does:**
    ```typescript
    activate_workflow({ id: "5", instance: "production" })
    ```

### Automatic Trigger Addition

!!! info "Smart Trigger Management"
    The MCP server automatically ensures workflows have valid triggers before activation:

    - If workflow has no trigger → Adds `scheduleTrigger` with default schedule
    - If workflow has `manualTrigger` only → Adds compatible trigger
    - n8n API v1.82.3 doesn't recognize `manualTrigger` as valid for activation

**Example:**
```
User: "Activate workflow 20"

Claude checks workflow 20:
- Has only manualTrigger node
- Adds scheduleTrigger node automatically
- Then activates workflow

Response: "Added schedule trigger and activated workflow"
```

### Activation Requirements

**Valid Triggers:**
- `scheduleTrigger` - Cron-based scheduling
- `webhook` - HTTP endpoint receiver
- Service-specific triggers (Slack, Email, etc.)

**Invalid Triggers:**
- `manualTrigger` - n8n API limitation (cannot activate)

### Best Practices

!!! tip "Before Activating"
    1. **Test manually** - Verify workflow works as expected
    2. **Check credentials** - Ensure all required credentials are configured
    3. **Verify schedule** - Confirm trigger settings are correct
    4. **Monitor initial runs** - Watch first few executions for issues

---

## deactivate_workflow

Disable a workflow to stop automatic execution.

### Purpose

Stop a workflow from running automatically. Useful for maintenance, debugging, or temporary suspension.

### Input Parameters

```typescript
{
  id: string;              // Workflow ID (required)
  instance?: string;       // n8n instance (optional)
}
```

### Output Format

```typescript
{
  id: string;
  name: string;
  active: boolean;         // Now false
  message?: string;
}
```

### Usage Examples

=== "Basic Deactivation"

    **Request:**
    ```
    Deactivate workflow 15
    ```

    **What Claude does:**
    ```typescript
    deactivate_workflow({ id: "15" })
    ```

    **Response:**
    ```
    ✅ Workflow "Daily Email Report" (ID: 15) has been deactivated!

    The workflow will no longer run automatically.
    You can still:
    - View workflow configuration
    - Check execution history
    - Reactivate when needed
    ```

=== "Batch Deactivation"

    **Request:**
    ```
    Deactivate all workflows tagged with "testing"
    ```

    **What Claude does:**
    ```typescript
    // Get testing tag ID
    const tags = get_tags()
    const testingTag = tags.find(t => t.name === "testing")

    // List workflows with testing tag
    const workflows = list_workflows({ tags: [testingTag.id] })

    // Deactivate each
    workflows.data.forEach(workflow => {
      deactivate_workflow({ id: workflow.id })
    })
    ```

### Use Cases

- **Maintenance** - Temporarily stop during updates
- **Debugging** - Prevent execution while troubleshooting
- **Resource Management** - Reduce load during peak times
- **Testing** - Stop production workflows before testing changes

---

## execute_workflow

Attempt to manually execute a workflow (with API limitations).

### Purpose

Provides guidance on manual workflow execution. Note that n8n REST API v1.82.3 has limitations for manual execution.

### Input Parameters

```typescript
{
  id: string;              // Workflow ID (required)
  instance?: string;       // n8n instance (optional)
}
```

### Output Format

```typescript
{
  success: boolean;
  message: string;         // Guidance or error explanation
  executionId?: string;    // If execution started
}
```

### API Limitations

!!! warning "n8n API Limitation"
    **Manual execution via REST API is limited:**

    - **Schedule triggers** - Cannot be executed manually via API
    - **Manual triggers** - Not supported for API execution
    - **Most triggers** - Designed for automatic activation only

    **Workaround:** Use n8n web interface for manual testing

### Usage Examples

=== "Execution Attempt"

    **Request:**
    ```
    Execute workflow 15 manually
    ```

    **What Claude does:**
    ```typescript
    execute_workflow({ id: "15" })
    ```

    **Response:**
    ```
    ⚠️ Manual Execution Limitation

    Workflow "Daily Email Report" (ID: 15) uses a schedule trigger,
    which cannot be executed manually via the n8n REST API.

    To test this workflow:
    1. Open workflow in n8n web interface:
       https://your-n8n-instance.com/workflow/15
    2. Click "Execute Workflow" button
    3. View execution results in the UI

    Alternatively:
    - Wait for next scheduled execution
    - Check execution history: "Show executions for workflow 15"
    ```

### Alternative Testing Methods

**Option 1: n8n Web Interface**
```
1. Navigate to workflow in n8n
2. Click "Execute Workflow" button
3. View real-time execution
```

**Option 2: Webhook Testing**
```
For webhook workflows:
curl -X POST https://your-n8n-instance.com/webhook/your-path \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'
```

**Option 3: Monitor Scheduled Execution**
```
User: "When is workflow 15 scheduled to run next?"
Claude: Shows next execution time based on trigger settings
```

---

## Common Workflows

### Complete Workflow Lifecycle

```
1. Create workflow
   → create_workflow()

2. Review configuration
   → get_workflow()

3. Test and refine
   → update_workflow()

4. Activate for production
   → activate_workflow()

5. Monitor executions
   → list_executions() (see Executions Management)

6. Deactivate for maintenance
   → deactivate_workflow()

7. Delete when obsolete
   → delete_workflow()
```

### Batch Operations

**Activate all inactive workflows:**
```
1. list_workflows({ active: false })
2. For each workflow:
   - activate_workflow({ id })
```

**Tag all workflows by pattern:**
```
1. list_workflows()
2. Filter workflows by name pattern
3. create_tag() for new tag
4. update_workflow() to add tag to each
```

---

## Next Steps

- **[Execution Management](executions-management.md)** - Monitor workflow runs
- **[Tag Management](tags-management.md)** - Organize workflows
- **[Examples](../examples/basic/webhook-workflow.md)** - Real-world patterns
- **[API Reference](../api/workflows-api.md)** - Technical specifications

---

!!! question "Need Help?"
    - [Troubleshooting Guide](../troubleshooting/error-reference.md)
    - [GitHub Issues](https://github.com/salacoste/mcp-n8n-workflow-builder/issues)