get_execution

Instructions

Implementation Reference

• src/tool-handlers/execution-tools.ts:138-209 (handler)

  The handler function that implements the get_execution tool logic: validates input, calls N8nApiClient to fetch execution data, formats a human-readable summary with status, timings, and duration, and returns formatted text output or error.

  export async function handle_get_execution(
  	api_client: N8nApiClient,
  	args: any,
  ) {
  	if (!args.id) {
  		throw new McpError(
  			ErrorCode.InvalidParams,
  			'Execution ID is required',
  		);
  	}
  
  	try {
  		const execution = await api_client.get_execution(
  			args.id,
  			args.includeData,
  		);
  
  		// Format a summary of the execution
  		const status = execution.finished
  			? execution.status === 'success'
  				? 'Successful'
  				: 'Failed'
  			: 'Running';
  
  		const start_time = new Date(execution.startedAt).toLocaleString();
  		const end_time = execution.stoppedAt
  			? new Date(execution.stoppedAt).toLocaleString()
  			: 'Still running';
  
  		const duration = execution.stoppedAt
  			? (new Date(execution.stoppedAt).getTime() -
  					new Date(execution.startedAt).getTime()) /
  			  1000
  			: null;
  
  		const duration_text =
  			duration !== null
  				? `${duration.toFixed(2)} seconds`
  				: 'Still running';
  
  		const summary = `Execution ID: ${args.id}
  Status: ${status}
  Workflow: ${execution.workflow_data?.name || 'Unknown'} (ID: ${
  			execution.workflowId
  		})
  Mode: ${execution.mode}
  Started: ${start_time}
  Ended: ${end_time}
  Duration: ${duration_text}`;
  
  		return {
  			content: [
  				{
  					type: 'text',
  					text: format_output(summary, execution, args.verbosity),
  				},
  			],
  		};
  	} catch (error: any) {
  		return {
  			content: [
  				{
  					type: 'text',
  					text: `Error retrieving execution: ${
  						error.message || String(error)
  					}`,
  				},
  			],
  			isError: true,
  		};
  	}
  }

• src/tool-handlers/index.ts:283-308 (schema)

  Tool schema definition including name, description, and input schema for get_execution in the MCP tools list response.

  	name: 'get_execution',
  	description:
  		'Retrieves detailed information about a specific workflow execution, including execution time, status, and optionally the full data processed at each step. Particularly useful for debugging failed workflows or understanding data transformations between nodes.',
  	inputSchema: {
  		type: 'object',
  		properties: {
  			id: {
  				type: 'string',
  				description:
  					'ID of the execution to retrieve - can be obtained from list_executions',
  			},
  			includeData: {
  				type: 'boolean',
  				description:
  					'Whether to include detailed execution data showing the input/output at each node (may be large for complex workflows)',
  			},
  			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'],
  			},
  		},
  		required: ['id'],
  	},
  },

• src/tool-handlers/index.ts:336-337 (registration)

  Tool dispatch registration in the switch statement that routes calls to the handle_get_execution function.

  case 'get_execution':
  	return await handle_get_execution(api_client, args);

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

  Helper function used by the handler to format output based on verbosity level (concise summary or full JSON details).

  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:207-218 (helper)

  N8nApiClient method that performs the actual API request to retrieve execution data, called by the tool handler.

  async get_execution(
  	id: string,
  	include_data?: boolean,
  ): Promise<any> {
  	let endpoint = `/executions/${id}`;
  
  	if (include_data !== undefined) {
  		endpoint += `?includeData=${include_data}`;
  	}
  
  	return this.request<any>('GET', endpoint);
  }