list_executions

Instructions

Implementation Reference

• src/tool-handlers/execution-tools.ts:38-133 (handler)

  The primary handler function for the list_executions MCP tool. Fetches executions from N8n API, computes stats, formats detailed list with status, workflow, times, durations, and handles verbosity and errors.

  export async function handle_list_executions(
  	api_client: N8nApiClient,
  	args: any,
  ) {
  	try {
  		const executions = await api_client.list_executions(args);
  
  		if (!executions || executions.length === 0) {
  			return {
  				content: [
  					{
  						type: 'text',
  						text: 'No executions found.',
  					},
  				],
  			};
  		}
  
  		// Create a summary of the executions
  		const success_count = executions.filter(
  			(exec: any) => exec.finished && exec.status === 'success',
  		).length;
  		const failed_count = executions.filter(
  			(exec: any) => exec.finished && exec.status !== 'success',
  		).length;
  		const running_count = executions.filter(
  			(exec: any) => !exec.finished,
  		).length;
  
  		const summary =
  			`Found ${executions.length} execution${
  				executions.length !== 1 ? 's' : ''
  			} ` +
  			`(${success_count} successful, ${failed_count} failed, ${running_count} running):\n\n`;
  
  		// Create a list of executions with their basic info
  		const execution_list = executions
  			.map((exec: any, index: number) => {
  				const status = !exec.finished
  					? 'Running'
  					: exec.status === 'success'
  					? 'Successful'
  					: 'Failed';
  
  				const start_time = new Date(exec.startedAt).toLocaleString();
  				const end_time = exec.stoppedAt
  					? new Date(exec.stoppedAt).toLocaleString()
  					: 'Still running';
  
  				const duration = exec.stoppedAt
  					? (new Date(exec.stoppedAt).getTime() -
  							new Date(exec.startedAt).getTime()) /
  					  1000
  					: null;
  
  				const duration_text =
  					duration !== null
  						? `${duration.toFixed(2)} seconds`
  						: 'Still running';
  
  				return `${index + 1}. Execution ID: ${exec.id}
     Status: ${status}
     Workflow: ${exec.workflow_data?.name || 'Unknown'} (ID: ${
  					exec.workflowId
  				})
     Started: ${start_time}
     Duration: ${duration_text}`;
  			})
  			.join('\n\n');
  
  		return {
  			content: [
  				{
  					type: 'text',
  					text: format_output(
  						summary + execution_list,
  						executions,
  						args.verbosity,
  					),
  				},
  			],
  		};
  	} catch (error: any) {
  		return {
  			content: [
  				{
  					type: 'text',
  					text: `Error listing executions: ${
  						error.message || String(error)
  					}`,
  				},
  			],
  			isError: true,
  		};
  	}
  }

• src/tool-handlers/index.ts:251-281 (schema)

  MCP tool schema registration for list_executions, defining name, description, and inputSchema with parameters: workflowId, status, limit, verbosity.

  	name: 'list_executions',
  	description:
  		'Lists workflow execution history with details on success/failure status, duration, and timestamps. Use this tool to monitor workflow performance, troubleshoot issues, or verify that workflows are running as expected. Results can be filtered by workflow ID, status, and limited to a specific number.',
  	inputSchema: {
  		type: 'object',
  		properties: {
  			workflowId: {
  				type: 'string',
  				description:
  					'Filter executions by workflow ID - can be obtained from list_workflows',
  			},
  			status: {
  				type: 'string',
  				description:
  					'Filter by execution status (error, success, waiting)',
  				enum: ['error', 'success', 'waiting'],
  			},
  			limit: {
  				type: 'number',
  				description:
  					'Maximum number of executions to return - useful for workflows with many executions',
  			},
  			verbosity: {
  				type: 'string',
  				description:
  					'Output verbosity level (concise or full). Default is concise which preserves context window space. Use full when you need complete execution details.',
  				enum: ['concise', 'full'],
  			},
  		},
  	},
  },

• src/tool-handlers/index.ts:334-335 (registration)

  Registration of the list_executions handler in the switch statement for CallToolRequestSchema dispatching.

  case 'list_executions':
  	return await handle_list_executions(api_client, args);

• src/tool-handlers/execution-tools.ts:15-33 (helper)

  Helper function used by list_executions handler to format output based on verbosity (concise or full).

  function format_output(
  	summary: string,
  	details: any,
  	verbosity?: string,
  ): string {
  	// Use the provided verbosity parameter if available, otherwise fall back to config
  	const output_verbosity = verbosity || config.output_verbosity;
  
  	if (output_verbosity === 'full') {
  		return (
  			summary +
  			'\n\nFull details:\n' +
  			JSON.stringify(details, null, 2)
  		);
  	} else {
  		// Default to concise mode
  		return summary;
  	}
  }

• src/n8n-api-client.ts:174-202 (helper)

  N8nApiClient method called by the handler to fetch executions from the n8n REST API, supporting filters for workflowId, status, and limit.

  async list_executions(
  	options?: ListExecutionsOptions,
  ): Promise<any> {
  	let endpoint = '/executions';
  
  	if (options) {
  		const params = new URLSearchParams();
  
  		if (options.workflowId) {
  			params.append('workflowId', options.workflowId);
  		}
  
  		if (options.status) {
  			params.append('status', options.status);
  		}
  
  		if (options.limit) {
  			params.append('limit', String(options.limit));
  		}
  
  		const query_string = params.toString();
  		if (query_string) {
  			endpoint += `?${query_string}`;
  		}
  	}
  
  	const response = await this.request<any>('GET', endpoint);
  	return response.data || response;
  }