n8n-MCP

Instructions

Implementation Reference

• src/mcp/tools-n8n-manager.ts:333-414 (registration)

  Registration of the n8n_executions tool including name, description, and complete input schema definition.
  { name: 'n8n_executions', description: `Manage workflow executions: get details, list, or delete. Use action='get' with id for execution details, action='list' for listing executions, action='delete' to remove execution record.`, inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['get', 'list', 'delete'], description: 'Operation: get=get execution details, list=list executions, delete=delete execution' }, // For action='get' and action='delete' id: { type: 'string', description: 'Execution ID (required for action=get or action=delete)' }, // For action='get' - detail level mode: { type: 'string', enum: ['preview', 'summary', 'filtered', 'full', 'error'], description: 'For action=get: preview=structure only, summary=2 items (default), filtered=custom, full=all data, error=optimized error debugging' }, nodeNames: { type: 'array', items: { type: 'string' }, description: 'For action=get with mode=filtered: filter to specific nodes by name' }, itemsLimit: { type: 'number', description: 'For action=get with mode=filtered: items per node (0=structure, 2=default, -1=unlimited)' }, includeInputData: { type: 'boolean', description: 'For action=get: include input data in addition to output (default: false)' }, // Error mode specific parameters errorItemsLimit: { type: 'number', description: 'For action=get with mode=error: sample items from upstream node (default: 2, max: 100)' }, includeStackTrace: { type: 'boolean', description: 'For action=get with mode=error: include full stack trace (default: false, shows truncated)' }, includeExecutionPath: { type: 'boolean', description: 'For action=get with mode=error: include execution path leading to error (default: true)' }, fetchWorkflow: { type: 'boolean', description: 'For action=get with mode=error: fetch workflow for accurate upstream detection (default: true)' }, // For action='list' limit: { type: 'number', description: 'For action=list: number of executions to return (1-100, default: 100)' }, cursor: { type: 'string', description: 'For action=list: pagination cursor from previous response' }, workflowId: { type: 'string', description: 'For action=list: filter by workflow ID' }, projectId: { type: 'string', description: 'For action=list: filter by project ID (enterprise feature)' }, status: { type: 'string', enum: ['success', 'error', 'waiting'], description: 'For action=list: filter by execution status' }, includeData: { type: 'boolean', description: 'For action=list: include execution data (default: false)' } }, required: ['action'] } },
• src/mcp/handlers-n8n-manager.ts:1417-1543 (handler)

  Handler function for n8n_executions action='get'. Fetches execution data from n8n API, applies filtering/modes (preview, summary, filtered, full, error), processes with execution-processor for optimized output especially for error debugging.
  export async function handleGetExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse> { try { const client = ensureApiConfigured(context); // Parse and validate input with new parameters const schema = z.object({ id: z.string(), // Filtering parameters mode: z.enum(['preview', 'summary', 'filtered', 'full', 'error']).optional(), nodeNames: z.array(z.string()).optional(), itemsLimit: z.number().optional(), includeInputData: z.boolean().optional(), // Legacy parameter (backward compatibility) includeData: z.boolean().optional(), // Error mode specific parameters errorItemsLimit: z.number().min(0).max(100).optional(), includeStackTrace: z.boolean().optional(), includeExecutionPath: z.boolean().optional(), fetchWorkflow: z.boolean().optional() }); const params = schema.parse(args); const { id, mode, nodeNames, itemsLimit, includeInputData, includeData, errorItemsLimit, includeStackTrace, includeExecutionPath, fetchWorkflow } = params; /** * Map legacy includeData parameter to mode for backward compatibility * * Legacy behavior: * - includeData: undefined -> minimal execution summary (no data) * - includeData: false -> minimal execution summary (no data) * - includeData: true -> full execution data * * New behavior mapping: * - includeData: undefined -> no mode (minimal) * - includeData: false -> no mode (minimal) * - includeData: true -> mode: 'summary' (2 items per node, not full) * * Note: Legacy true behavior returned ALL data, which could exceed token limits. * New behavior caps at 2 items for safety. Users can use mode: 'full' for old behavior. */ let effectiveMode = mode; if (!effectiveMode && includeData !== undefined) { effectiveMode = includeData ? 'summary' : undefined; } // Determine if we need to fetch full data from API // We fetch full data if any mode is specified (including preview) or legacy includeData is true // Preview mode needs the data to analyze structure and generate recommendations const fetchFullData = effectiveMode !== undefined || includeData === true; // Fetch execution from n8n API const execution = await client.getExecution(id, fetchFullData); // If no filtering options specified, return original execution (backward compatibility) if (!effectiveMode && !nodeNames && itemsLimit === undefined) { return { success: true, data: execution }; } // For error mode, optionally fetch workflow for accurate upstream detection let workflow: Workflow | undefined; if (effectiveMode === 'error' && fetchWorkflow !== false && execution.workflowId) { try { workflow = await client.getWorkflow(execution.workflowId); } catch (e) { // Workflow fetch failed - continue without it (use heuristics) logger.debug('Could not fetch workflow for error analysis', { workflowId: execution.workflowId, error: e instanceof Error ? e.message : 'Unknown error' }); } } // Apply filtering using ExecutionProcessor const filterOptions: ExecutionFilterOptions = { mode: effectiveMode, nodeNames, itemsLimit, includeInputData, // Error mode specific options errorItemsLimit, includeStackTrace, includeExecutionPath }; const processedExecution = processExecution(execution, filterOptions, workflow); return { success: true, data: processedExecution }; } 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 }; } return { success: false, error: error instanceof Error ? error.message : 'Unknown error occurred' }; } }
• src/mcp/handlers-n8n-manager.ts:1545-1593 (handler)

  Handler function for n8n_executions action='list'. Lists executions with filters (workflowId, status, limit, cursor, projectId), supports pagination.
  export async function handleListExecutions(args: unknown, context?: InstanceContext): Promise<McpToolResponse> { try { const client = ensureApiConfigured(context); const input = listExecutionsSchema.parse(args || {}); const response = await client.listExecutions({ limit: input.limit || 100, cursor: input.cursor, workflowId: input.workflowId, projectId: input.projectId, status: input.status as ExecutionStatus | undefined, includeData: input.includeData || false }); return { success: true, data: { executions: response.data, returned: response.data.length, nextCursor: response.nextCursor, hasMore: !!response.nextCursor, ...(response.nextCursor ? { _note: "More executions available. Use cursor to get next page." } : {}) } }; } 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 }; } return { success: false, error: error instanceof Error ? error.message : 'Unknown error occurred' }; } }
• src/mcp/handlers-n8n-manager.ts:1595-1628 (handler)

  Handler function for n8n_executions action='delete'. Deletes a specific execution record by ID.
  export async function handleDeleteExecution(args: unknown, context?: InstanceContext): Promise<McpToolResponse> { try { const client = ensureApiConfigured(context); const { id } = z.object({ id: z.string() }).parse(args); await client.deleteExecution(id); return { success: true, message: `Execution ${id} deleted successfully` }; } 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 }; } return { success: false, error: error instanceof Error ? error.message : 'Unknown error occurred' }; } }
• src/mcp/tool-docs/workflow_management/n8n-executions.ts:1-108 (schema)

  Detailed tool documentation including full parameter descriptions, examples, best practices, use cases, and performance notes for n8n_executions.
  import { ToolDocumentation } from '../types'; export const n8nExecutionsDoc: ToolDocumentation = { name: 'n8n_executions', category: 'workflow_management', essentials: { description: 'Manage workflow executions: get details, list, or delete. Unified tool for all execution operations.', keyParameters: ['action', 'id', 'workflowId', 'status', 'mode'], example: 'n8n_executions({action: "get", id: "exec_456", mode: "error"})', performance: 'Fast (50-200ms)', tips: [ 'action="get": Get execution details by ID', 'action="list": List executions with filters', 'action="delete": Delete execution record', 'Use mode="error" for efficient failure debugging (80-90% token savings)', 'Use mode parameter for action=get to control detail level' ] }, full: { description: `**Actions:** - get: Retrieve execution details by ID with configurable detail level - list: List executions with filtering and pagination - delete: Remove an execution record from history **Detail Modes for action="get":** - preview: Structure only, no data - summary: 2 items per node (default) - filtered: Custom items limit, optionally filter by node names - full: All execution data (can be very large) - error: Optimized for debugging failures - extracts error info, upstream context, and AI suggestions **Error Mode Features:** - Extracts error message, type, and node configuration - Samples input data from upstream node (configurable limit) - Shows execution path leading to error - Provides AI-friendly fix suggestions based on error patterns - Token-efficient (80-90% smaller than full mode)`, parameters: { action: { type: 'string', required: true, description: 'Operation: "get", "list", or "delete"' }, id: { type: 'string', required: false, description: 'Execution ID (required for action=get or action=delete)' }, mode: { type: 'string', required: false, description: 'For action=get: "preview", "summary" (default), "filtered", "full", "error"' }, nodeNames: { type: 'array', required: false, description: 'For action=get with mode=filtered: Filter to specific nodes by name' }, itemsLimit: { type: 'number', required: false, description: 'For action=get with mode=filtered: Items per node (0=structure, 2=default, -1=unlimited)' }, includeInputData: { type: 'boolean', required: false, description: 'For action=get: Include input data in addition to output (default: false)' }, errorItemsLimit: { type: 'number', required: false, description: 'For action=get with mode=error: Sample items from upstream (default: 2, max: 100)' }, includeStackTrace: { type: 'boolean', required: false, description: 'For action=get with mode=error: Include full stack trace (default: false, shows truncated)' }, includeExecutionPath: { type: 'boolean', required: false, description: 'For action=get with mode=error: Include execution path (default: true)' }, fetchWorkflow: { type: 'boolean', required: false, description: 'For action=get with mode=error: Fetch workflow for accurate upstream detection (default: true)' }, workflowId: { type: 'string', required: false, description: 'For action=list: Filter by workflow ID' }, status: { type: 'string', required: false, description: 'For action=list: Filter by status ("success", "error", "waiting")' }, limit: { type: 'number', required: false, description: 'For action=list: Number of results (1-100, default: 100)' }, cursor: { type: 'string', required: false, description: 'For action=list: Pagination cursor from previous response' }, projectId: { type: 'string', required: false, description: 'For action=list: Filter by project ID (enterprise)' }, includeData: { type: 'boolean', required: false, description: 'For action=list: Include execution data (default: false)' } }, returns: `Depends on action: - get (error mode): { errorInfo: { primaryError, upstreamContext, executionPath, suggestions }, summary } - get (other modes): Execution object with data based on mode - list: { data: [...executions], nextCursor?: string } - delete: { success: boolean, message: string }`, examples: [ '// Debug a failed execution (recommended for errors)\nn8n_executions({action: "get", id: "exec_456", mode: "error"})', '// Debug with more sample data from upstream\nn8n_executions({action: "get", id: "exec_456", mode: "error", errorItemsLimit: 5})', '// Debug with full stack trace\nn8n_executions({action: "get", id: "exec_456", mode: "error", includeStackTrace: true})', '// Debug without workflow fetch (faster but less accurate)\nn8n_executions({action: "get", id: "exec_456", mode: "error", fetchWorkflow: false})', '// List recent executions for a workflow\nn8n_executions({action: "list", workflowId: "abc123", limit: 10})', '// List failed executions\nn8n_executions({action: "list", status: "error"})', '// Get execution summary\nn8n_executions({action: "get", id: "exec_456"})', '// Get full execution data\nn8n_executions({action: "get", id: "exec_456", mode: "full"})', '// Get specific nodes from execution\nn8n_executions({action: "get", id: "exec_456", mode: "filtered", nodeNames: ["HTTP Request", "Slack"]})', '// Delete an execution\nn8n_executions({action: "delete", id: "exec_456"})' ], useCases: [ 'Debug workflow failures efficiently (mode=error) - 80-90% token savings', 'Get AI suggestions for fixing common errors', 'Analyze input data that caused failure', 'Debug workflow failures with full data (mode=full)', 'Monitor workflow health (list with status filter)', 'Audit execution history', 'Clean up old execution records', 'Analyze specific node outputs' ], performance: `Response times: - list: 50-150ms depending on filters - get (preview/summary): 30-100ms - get (error): 50-200ms (includes optional workflow fetch) - get (full): 100-500ms+ depending on data size - delete: 30-80ms`, bestPractices: [ 'Use mode="error" for debugging failed executions - 80-90% token savings vs full', 'Use mode="summary" (default) for quick inspection', 'Use mode="filtered" with nodeNames for large workflows', 'Filter by workflowId when listing to reduce results', 'Use cursor for pagination through large result sets', 'Set fetchWorkflow=false if you already know the workflow structure', 'Delete old executions to save storage' ], pitfalls: [ 'Requires N8N_API_URL and N8N_API_KEY configured', 'mode="full" can return very large responses for complex workflows', 'mode="error" fetches workflow by default (adds ~50-100ms), disable with fetchWorkflow=false', 'Execution must exist or returns 404', 'Delete is permanent - cannot undo' ], relatedTools: ['n8n_get_workflow', 'n8n_test_workflow', 'n8n_validate_workflow'] } };