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 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¶

{
  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¶

{
  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 my n8n workflows

list_workflows()

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 ...]

Show only active workflows

list_workflows({ active: true })

You have 8 active workflows:

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

Show workflows tagged with "production"

// First, get tag ID
get_tags() // Find "production" tag ID

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

List workflows in staging environment

list_workflows({ instance: "staging" })

Performance Notes¶

Error Handling¶

Common Errors:

get_workflow¶

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

Purpose¶

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

Input Parameters¶

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

Output Format¶

{
  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¶

Show me workflow 15

get_workflow({ id: "15" })

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

Get workflow 5 from production

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¶

{
  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¶

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

Usage Examples¶

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

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

Create a webhook workflow "Order Processor" that receives orders and saves them

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¶

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¶

{
  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¶

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

Usage Examples¶

Rename workflow 15 to "Daily Email Alerts"

update_workflow({
  id: "15",
  name: "Daily Email Alerts"
})

Update workflow 10 to send email to new-email@example.com

// 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 a Slack notification node to workflow 5 after the email node

// 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¶

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¶

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

Output Format¶

{
  success: boolean;
  message: string;
}

Usage Examples¶

Delete workflow 99

delete_workflow({ id: "99" })

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

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

Delete the "Temporary Test" workflow

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?

Yes, delete it

delete_workflow({ id: "42" })

Safety Considerations¶

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¶

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

Output Format¶

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

Usage Examples¶

Activate workflow 15

activate_workflow({ id: "15" })

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

Activate workflow 5 in production

activate_workflow({ id: "5", instance: "production" })

Automatic Trigger Addition¶

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¶

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¶

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

Output Format¶

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

Usage Examples¶

Deactivate workflow 15

deactivate_workflow({ id: "15" })

✅ 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

Deactivate all workflows tagged with "testing"

// 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¶

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

Output Format¶

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

API Limitations¶

Usage Examples¶

Execute workflow 15 manually

execute_workflow({ id: "15" })

⚠️ 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 - Monitor workflow runs
• Tag Management - Organize workflows
• Examples - Real-world patterns
• API Reference - Technical specifications