n8n-MCP

Instructions

Implementation Reference

• src/mcp/handlers-n8n-manager.ts:1263-1415 (handler)

  Main handler function that implements the core logic for the 'n8n_test_workflow' tool. Fetches workflow, auto-detects or validates trigger type (webhook/form/chat), checks prerequisites (active status, required params), retrieves appropriate trigger handler from registry, and executes the trigger.

  export async function handleTestWorkflow(args: unknown, context?: InstanceContext): Promise<McpToolResponse> {
    try {
      const client = ensureApiConfigured(context);
      const input = testWorkflowSchema.parse(args);
  
      // Import trigger system (lazy to avoid circular deps)
      const {
        detectTriggerFromWorkflow,
        ensureRegistryInitialized,
        TriggerRegistry,
      } = await import('../triggers');
  
      // Ensure registry is initialized
      await ensureRegistryInitialized();
  
      // Fetch the workflow to analyze its trigger
      const workflow = await client.getWorkflow(input.workflowId);
  
      // Determine trigger type
      let triggerType: TriggerType | undefined = input.triggerType as TriggerType | undefined;
      let triggerInfo;
  
      // Auto-detect from workflow
      const detection = detectTriggerFromWorkflow(workflow);
  
      if (!triggerType) {
        if (detection.detected && detection.trigger) {
          triggerType = detection.trigger.type;
          triggerInfo = detection.trigger;
        } else {
          // No externally-triggerable trigger found
          return {
            success: false,
            error: 'Workflow cannot be triggered externally',
            details: {
              workflowId: input.workflowId,
              reason: detection.reason,
              hint: 'Only workflows with webhook, form, or chat triggers can be executed via the API. Add one of these trigger nodes to your workflow.',
            },
          };
        }
      } else {
        // User specified a trigger type, verify it matches workflow
        if (detection.detected && detection.trigger?.type === triggerType) {
          triggerInfo = detection.trigger;
        } else if (!detection.detected || detection.trigger?.type !== triggerType) {
          return {
            success: false,
            error: `Workflow does not have a ${triggerType} trigger`,
            details: {
              workflowId: input.workflowId,
              requestedTrigger: triggerType,
              detectedTrigger: detection.trigger?.type || 'none',
              hint: detection.detected
                ? `Workflow has a ${detection.trigger?.type} trigger. Either use that type or omit triggerType for auto-detection.`
                : 'Workflow has no externally-triggerable triggers (webhook, form, or chat).',
            },
          };
        }
      }
  
      // Get handler for trigger type
      const handler = TriggerRegistry.getHandler(triggerType, client, context);
      if (!handler) {
        return {
          success: false,
          error: `No handler registered for trigger type: ${triggerType}`,
          details: {
            supportedTypes: TriggerRegistry.getRegisteredTypes(),
          },
        };
      }
  
      // Check if workflow is active (if required by handler)
      if (handler.capabilities.requiresActiveWorkflow && !workflow.active) {
        return {
          success: false,
          error: 'Workflow must be active to trigger via this method',
          details: {
            workflowId: input.workflowId,
            triggerType,
            hint: 'Activate the workflow in n8n using n8n_update_partial_workflow with [{type: "activateWorkflow"}]',
          },
        };
      }
  
      // Validate chat trigger has message
      if (triggerType === 'chat' && !input.message) {
        return {
          success: false,
          error: 'Chat trigger requires a message parameter',
          details: {
            hint: 'Provide message="your message" for chat triggers',
          },
        };
      }
  
      // Build trigger-specific input
      const triggerInput = {
        workflowId: input.workflowId,
        triggerType,
        httpMethod: input.httpMethod,
        webhookPath: input.webhookPath,
        message: input.message || '',
        sessionId: input.sessionId,
        data: input.data,
        formData: input.data, // For form triggers
        headers: input.headers,
        timeout: input.timeout,
        waitForResponse: input.waitForResponse,
      };
  
      // Execute the trigger
      const response = await handler.execute(triggerInput as any, workflow, triggerInfo);
  
      return {
        success: response.success,
        data: response.data,
        message: response.success
          ? `Workflow triggered successfully via ${triggerType}`
          : response.error,
        executionId: response.executionId,
        workflowId: input.workflowId,
        details: {
          triggerType,
          metadata: response.metadata,
          ...(response.details || {}),
        },
      };
    } catch (error) {
      if (error instanceof z.ZodError) {
        return {
          success: false,
          error: 'Invalid input',
          details: { errors: error.errors },
        };
      }
  
      if (error instanceof N8nApiError) {
        return {
          success: false,
          error: getUserFriendlyErrorMessage(error),
          code: error.code,
          details: error.details as Record<string, unknown> | undefined,
        };
      }
  
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error occurred',
      };
    }
  }

• src/mcp/tools-n8n-manager.ts:279-331 (schema)

  ToolDefinition object defining the 'n8n_test_workflow' tool for MCP registration, including name, description, and complete inputSchema for parameter validation.

  name: 'n8n_test_workflow',
  description: `Test/trigger workflow execution. Auto-detects trigger type (webhook/form/chat). Supports: webhook (HTTP), form (fields), chat (message). Note: Only workflows with these trigger types can be executed externally.`,
  inputSchema: {
    type: 'object',
    properties: {
      workflowId: {
        type: 'string',
        description: 'Workflow ID to execute (required)'
      },
      triggerType: {
        type: 'string',
        enum: ['webhook', 'form', 'chat'],
        description: 'Trigger type. Auto-detected if not specified. Workflow must have a matching trigger node.'
      },
      // Webhook options
      httpMethod: {
        type: 'string',
        enum: ['GET', 'POST', 'PUT', 'DELETE'],
        description: 'For webhook: HTTP method (default: from workflow config or POST)'
      },
      webhookPath: {
        type: 'string',
        description: 'For webhook: override the webhook path'
      },
      // Chat options
      message: {
        type: 'string',
        description: 'For chat: message to send (required for chat triggers)'
      },
      sessionId: {
        type: 'string',
        description: 'For chat: session ID for conversation continuity'
      },
      // Common options
      data: {
        type: 'object',
        description: 'Input data/payload for webhook, form fields, or execution data'
      },
      headers: {
        type: 'object',
        description: 'Custom HTTP headers'
      },
      timeout: {
        type: 'number',
        description: 'Timeout in ms (default: 120000)'
      },
      waitForResponse: {
        type: 'boolean',
        description: 'Wait for workflow completion (default: true)'
      }
    },
    required: ['workflowId']
  }

• src/mcp/tool-docs/workflow_management/n8n-test-workflow.ts:3-138 (schema)

  Comprehensive ToolDocumentation providing detailed descriptions, parameter specs, examples, performance notes, best practices, pitfalls, and related tools for 'n8n_test_workflow'.

  export const n8nTestWorkflowDoc: ToolDocumentation = {
    name: 'n8n_test_workflow',
    category: 'workflow_management',
    essentials: {
      description: 'Test/trigger workflow execution. Auto-detects trigger type (webhook/form/chat). Only workflows with these triggers can be executed externally.',
      keyParameters: ['workflowId', 'triggerType', 'data', 'message'],
      example: 'n8n_test_workflow({workflowId: "123"}) - auto-detect trigger',
      performance: 'Immediate trigger, response time depends on workflow complexity',
      tips: [
        'Auto-detects trigger type from workflow if not specified',
        'Workflow must have a webhook, form, or chat trigger to be executable',
        'For chat triggers, message is required',
        'All trigger types require the workflow to be ACTIVE'
      ]
    },
    full: {
      description: `Test and trigger n8n workflows through HTTP-based methods. This unified tool supports multiple trigger types:
  
  **Trigger Types:**
  - **webhook**: HTTP-based triggers (GET/POST/PUT/DELETE)
  - **form**: Form submission triggers
  - **chat**: AI chat triggers with conversation support
  
  **Important:** n8n's public API does not support direct workflow execution. Only workflows with webhook, form, or chat triggers can be executed externally. Workflows with schedule, manual, or other trigger types cannot be triggered via this API.
  
  The tool auto-detects the appropriate trigger type by analyzing the workflow's trigger node. You can override this with the triggerType parameter.`,
      parameters: {
        workflowId: {
          type: 'string',
          required: true,
          description: 'Workflow ID to execute'
        },
        triggerType: {
          type: 'string',
          required: false,
          enum: ['webhook', 'form', 'chat'],
          description: 'Trigger type. Auto-detected if not specified. Workflow must have matching trigger node.'
        },
        httpMethod: {
          type: 'string',
          required: false,
          enum: ['GET', 'POST', 'PUT', 'DELETE'],
          description: 'For webhook: HTTP method (default: from workflow config or POST)'
        },
        webhookPath: {
          type: 'string',
          required: false,
          description: 'For webhook: override the webhook path'
        },
        message: {
          type: 'string',
          required: false,
          description: 'For chat: message to send (required for chat triggers)'
        },
        sessionId: {
          type: 'string',
          required: false,
          description: 'For chat: session ID for conversation continuity'
        },
        data: {
          type: 'object',
          required: false,
          description: 'Input data/payload for webhook or form fields'
        },
        headers: {
          type: 'object',
          required: false,
          description: 'Custom HTTP headers'
        },
        timeout: {
          type: 'number',
          required: false,
          description: 'Timeout in ms (default: 120000)'
        },
        waitForResponse: {
          type: 'boolean',
          required: false,
          description: 'Wait for workflow completion (default: true)'
        }
      },
      returns: `Execution response including:
  - success: boolean
  - data: workflow output data
  - executionId: for tracking/debugging
  - triggerType: detected or specified trigger type
  - metadata: timing and request details`,
      examples: [
        'n8n_test_workflow({workflowId: "123"}) - Auto-detect and trigger',
        'n8n_test_workflow({workflowId: "123", triggerType: "webhook", data: {name: "John"}}) - Webhook with data',
        'n8n_test_workflow({workflowId: "123", triggerType: "chat", message: "Hello AI"}) - Chat trigger',
        'n8n_test_workflow({workflowId: "123", triggerType: "form", data: {email: "test@example.com"}}) - Form submission'
      ],
      useCases: [
        'Test workflows during development',
        'Trigger AI chat workflows with messages',
        'Submit form data to form-triggered workflows',
        'Integrate n8n workflows with external systems via webhooks'
      ],
      performance: `Performance varies based on workflow complexity and waitForResponse setting:
  - Webhook: Immediate trigger, depends on workflow
  - Form: Immediate trigger, depends on workflow
  - Chat: May have additional AI processing time`,
      errorHandling: `**Error Response with Execution Guidance**
  
  When execution fails, the response includes guidance for debugging:
  
  **With Execution ID** (workflow started but failed):
  - Use n8n_executions({action: 'get', id: executionId, mode: 'preview'}) to investigate
  
  **Without Execution ID** (workflow didn't start):
  - Use n8n_executions({action: 'list', workflowId: 'wf_id'}) to find recent executions
  
  **Common Errors:**
  - "Workflow not found" - Check workflow ID exists
  - "Workflow not active" - Activate workflow (required for all trigger types)
  - "Workflow cannot be triggered externally" - Workflow has no webhook/form/chat trigger
  - "Chat message required" - Provide message parameter for chat triggers
  - "SSRF protection" - URL validation failed`,
      bestPractices: [
        'Let auto-detection choose the trigger type when possible',
        'Ensure workflow has a webhook, form, or chat trigger before testing',
        'For chat workflows, provide sessionId for multi-turn conversations',
        'Use mode="preview" with n8n_executions for efficient debugging',
        'Test with small data payloads first',
        'Activate workflows before testing (use n8n_update_partial_workflow with activateWorkflow)'
      ],
      pitfalls: [
        'All trigger types require the workflow to be ACTIVE',
        'Workflows without webhook/form/chat triggers cannot be executed externally',
        'Chat trigger requires message parameter',
        'Form data must match expected form fields',
        'Webhook method must match node configuration'
      ],
      relatedTools: ['n8n_executions', 'n8n_get_workflow', 'n8n_create_workflow', 'n8n_validate_workflow']
    }
  };

• src/mcp/tools-n8n-manager.ts:278-332 (registration)

  The tool is registered as part of the n8nManagementTools array exported from this file, which is imported and used by the MCP server to register management tools.

  {
    name: 'n8n_test_workflow',
    description: `Test/trigger workflow execution. Auto-detects trigger type (webhook/form/chat). Supports: webhook (HTTP), form (fields), chat (message). Note: Only workflows with these trigger types can be executed externally.`,
    inputSchema: {
      type: 'object',
      properties: {
        workflowId: {
          type: 'string',
          description: 'Workflow ID to execute (required)'
        },
        triggerType: {
          type: 'string',
          enum: ['webhook', 'form', 'chat'],
          description: 'Trigger type. Auto-detected if not specified. Workflow must have a matching trigger node.'
        },
        // Webhook options
        httpMethod: {
          type: 'string',
          enum: ['GET', 'POST', 'PUT', 'DELETE'],
          description: 'For webhook: HTTP method (default: from workflow config or POST)'
        },
        webhookPath: {
          type: 'string',
          description: 'For webhook: override the webhook path'
        },
        // Chat options
        message: {
          type: 'string',
          description: 'For chat: message to send (required for chat triggers)'
        },
        sessionId: {
          type: 'string',
          description: 'For chat: session ID for conversation continuity'
        },
        // Common options
        data: {
          type: 'object',
          description: 'Input data/payload for webhook, form fields, or execution data'
        },
        headers: {
          type: 'object',
          description: 'Custom HTTP headers'
        },
        timeout: {
          type: 'number',
          description: 'Timeout in ms (default: 120000)'
        },
        waitForResponse: {
          type: 'boolean',
          description: 'Wait for workflow completion (default: true)'
        }
      },
      required: ['workflowId']
    }
  },

• src/triggers/index.ts:1-47 (helper)

  Central export module for the trigger system used by n8n_test_workflow handler, providing trigger detection, registry, and base handler functionality.

  /**
   * Trigger system for n8n_test_workflow tool
   *
   * Provides extensible trigger handling for different n8n trigger types:
   * - webhook: HTTP-based triggers
   * - form: Form submission triggers
   * - chat: Chat/AI triggers
   *
   * Note: n8n's public API does not support direct workflow execution.
   * Only workflows with these trigger types can be triggered externally.
   */
  
  // Types
  export {
    TriggerType,
    BaseTriggerInput,
    WebhookTriggerInput,
    FormTriggerInput,
    ChatTriggerInput,
    TriggerInput,
    TriggerResponse,
    TriggerHandlerCapabilities,
    DetectedTrigger,
    TriggerDetectionResult,
    TestWorkflowInput,
  } from './types';
  
  // Detector
  export {
    detectTriggerFromWorkflow,
    buildTriggerUrl,
    describeTrigger,
  } from './trigger-detector';
  
  // Registry
  export {
    TriggerRegistry,
    initializeTriggerRegistry,
    ensureRegistryInitialized,
  } from './trigger-registry';
  
  // Base handler
  export {
    BaseTriggerHandler,
    TriggerHandlerConstructor,
  } from './handlers/base-handler';