n8n-MCP

Instructions

Implementation Reference

• src/mcp/handlers-n8n-manager.ts:2391-2592 (handler)

  Core implementation of n8n_deploy_template tool. Fetches template by ID from local database, processes it (strips credentials if requested, upgrades node versions, auto-fixes issues), deploys to n8n instance via API creating inactive workflow, returns workflow ID, required credentials list, fixes applied, and n8n UI URL.
  export async function handleDeployTemplate( args: unknown, templateService: TemplateService, repository: NodeRepository, context?: InstanceContext ): Promise<McpToolResponse> { try { const client = ensureApiConfigured(context); const input = deployTemplateSchema.parse(args); // Fetch template const template = await templateService.getTemplate(input.templateId, 'full'); if (!template) { return { success: false, error: `Template ${input.templateId} not found`, details: { hint: 'Use search_templates to find available templates', templateUrl: `https://n8n.io/workflows/${input.templateId}` } }; } // Extract workflow from template (deep copy to avoid mutation) const workflow = JSON.parse(JSON.stringify(template.workflow)); if (!workflow || !workflow.nodes) { return { success: false, error: 'Template has invalid workflow structure', details: { templateId: input.templateId } }; } // Set workflow name const workflowName = input.name || template.name; // Collect required credentials before stripping const requiredCredentials: RequiredCredential[] = []; for (const node of workflow.nodes) { if (node.credentials && typeof node.credentials === 'object') { for (const [credType] of Object.entries(node.credentials)) { requiredCredentials.push({ nodeType: node.type, nodeName: node.name, credentialType: credType }); } } } // Strip credentials if requested if (input.stripCredentials) { workflow.nodes = workflow.nodes.map((node: any) => { const { credentials, ...rest } = node; return rest; }); } // Auto-upgrade typeVersions if requested if (input.autoUpgradeVersions) { const autoFixer = new WorkflowAutoFixer(repository); // Run validation to get issues to fix const validator = new WorkflowValidator(repository, EnhancedConfigValidator); const validationResult = await validator.validateWorkflow(workflow, { validateNodes: true, validateConnections: false, validateExpressions: false, profile: 'runtime' }); // Generate fixes focused on typeVersion upgrades const fixResult = await autoFixer.generateFixes( workflow, validationResult, [], { fixTypes: ['typeversion-upgrade', 'typeversion-correction'] } ); // Apply fixes to workflow if (fixResult.operations.length > 0) { for (const op of fixResult.operations) { if (op.type === 'updateNode' && op.updates) { const node = workflow.nodes.find((n: any) => n.id === op.nodeId || n.name === op.nodeName ); if (node) { for (const [path, value] of Object.entries(op.updates)) { if (path === 'typeVersion') { node.typeVersion = value; } } } } } } } // Identify trigger type const triggerNode = workflow.nodes.find((n: any) => n.type?.includes('Trigger') || n.type?.includes('webhook') || n.type === 'n8n-nodes-base.webhook' ); const triggerType = triggerNode?.type?.split('.').pop() || 'manual'; // Create workflow via API (always creates inactive) // Deploy first, then fix - this ensures the workflow exists before we modify it const createdWorkflow = await client.createWorkflow({ name: workflowName, nodes: workflow.nodes, connections: workflow.connections, settings: workflow.settings || { executionOrder: 'v1' } }); // Get base URL for workflow link const apiConfig = context ? getN8nApiConfigFromContext(context) : getN8nApiConfig(); const baseUrl = apiConfig?.baseUrl?.replace('/api/v1', '') || ''; // Auto-fix common issues after deployment (expression format, etc.) let fixesApplied: AppliedFix[] = []; let fixSummary = ''; let autoFixStatus: 'success' | 'failed' | 'skipped' = 'skipped'; if (input.autoFix) { try { // Run autofix on the deployed workflow const autofixResult = await handleAutofixWorkflow( { id: createdWorkflow.id, applyFixes: true, fixTypes: ['expression-format', 'typeversion-upgrade'], confidenceThreshold: 'medium' }, repository, context ); if (autofixResult.success && autofixResult.data) { const fixData = autofixResult.data as AutofixResultData; autoFixStatus = 'success'; if (fixData.fixesApplied && fixData.fixesApplied > 0) { fixesApplied = fixData.fixes || []; fixSummary = ` Auto-fixed ${fixData.fixesApplied} issue(s).`; } } } catch (fixError) { // Log but don't fail - autofix is best-effort autoFixStatus = 'failed'; logger.warn('Auto-fix failed after template deployment', { workflowId: createdWorkflow.id, error: fixError instanceof Error ? fixError.message : 'Unknown error' }); fixSummary = ' Auto-fix failed (workflow deployed successfully).'; } } return { success: true, data: { workflowId: createdWorkflow.id, name: createdWorkflow.name, active: false, nodeCount: workflow.nodes.length, triggerType, requiredCredentials: requiredCredentials.length > 0 ? requiredCredentials : undefined, url: baseUrl ? `${baseUrl}/workflow/${createdWorkflow.id}` : undefined, templateId: input.templateId, templateUrl: template.url || `https://n8n.io/workflows/${input.templateId}`, autoFixStatus, fixesApplied: fixesApplied.length > 0 ? fixesApplied : undefined }, message: `Workflow "${createdWorkflow.name}" deployed successfully from template ${input.templateId}.${fixSummary} ${ requiredCredentials.length > 0 ? `Configure ${requiredCredentials.length} credential(s) in n8n to activate.` : '' }` }; } 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:492-524 (schema)

  ToolDefinition object defining the tool name, description, and inputSchema for validation. Part of n8nManagementTools array export.
  { name: 'n8n_deploy_template', description: `Deploy a workflow template from n8n.io directly to your n8n instance. Deploys first, then auto-fixes common issues (expression format, typeVersions). Returns workflow ID, required credentials, and fixes applied.`, inputSchema: { type: 'object', properties: { templateId: { type: 'number', description: 'Template ID from n8n.io (required)' }, name: { type: 'string', description: 'Custom workflow name (default: template name)' }, autoUpgradeVersions: { type: 'boolean', default: true, description: 'Automatically upgrade node typeVersions to latest supported (default: true)' }, autoFix: { type: 'boolean', default: true, description: 'Auto-apply fixes after deployment for expression format issues, missing = prefix, etc. (default: true)' }, stripCredentials: { type: 'boolean', default: true, description: 'Remove credential references from nodes - user configures in n8n UI (default: true)' } }, required: ['templateId'] } }
• src/mcp/tools-n8n-manager.ts:492-525 (registration)

  The tool is defined and exported as part of the n8nManagementTools array, which is imported and registered in the MCP engine.
  { name: 'n8n_deploy_template', description: `Deploy a workflow template from n8n.io directly to your n8n instance. Deploys first, then auto-fixes common issues (expression format, typeVersions). Returns workflow ID, required credentials, and fixes applied.`, inputSchema: { type: 'object', properties: { templateId: { type: 'number', description: 'Template ID from n8n.io (required)' }, name: { type: 'string', description: 'Custom workflow name (default: template name)' }, autoUpgradeVersions: { type: 'boolean', default: true, description: 'Automatically upgrade node typeVersions to latest supported (default: true)' }, autoFix: { type: 'boolean', default: true, description: 'Auto-apply fixes after deployment for expression format issues, missing = prefix, etc. (default: true)' }, stripCredentials: { type: 'boolean', default: true, description: 'Remove credential references from nodes - user configures in n8n UI (default: true)' } }, required: ['templateId'] } } ];
• src/mcp/tool-docs/workflow_management/n8n-deploy-template.ts:1-72 (helper)

  Detailed documentation structure for the tool, used by the tools_documentation tool to provide help and examples.
  import { ToolDocumentation } from '../types'; export const n8nDeployTemplateDoc: ToolDocumentation = { name: 'n8n_deploy_template', category: 'workflow_management', essentials: { description: 'Deploy a workflow template from n8n.io directly to your n8n instance. Deploys first, then auto-fixes common issues (expression format, typeVersions).', keyParameters: ['templateId', 'name', 'autoUpgradeVersions', 'autoFix', 'stripCredentials'], example: 'n8n_deploy_template({templateId: 2776, name: "My Deployed Template"})', performance: 'Network-dependent', tips: [ 'Auto-fixes expression format issues after deployment', 'Workflow created inactive - configure credentials in n8n UI first', 'Returns list of required credentials and fixes applied', 'Use search_templates to find template IDs' ] }, full: { description: 'Deploys a workflow template from n8n.io directly to your n8n instance. This tool deploys first, then automatically fixes common issues like missing expression prefixes (=) and outdated typeVersions. Templates are stored locally and fetched from the database. The workflow is always created in an inactive state, allowing you to configure credentials before activation.', parameters: { templateId: { type: 'number', required: true, description: 'Template ID from n8n.io (find via search_templates)' }, name: { type: 'string', description: 'Custom workflow name (default: template name)' }, autoUpgradeVersions: { type: 'boolean', description: 'Upgrade node typeVersions to latest supported (default: true)' }, autoFix: { type: 'boolean', description: 'Auto-apply fixes after deployment for expression format issues, missing = prefix, etc. (default: true)' }, stripCredentials: { type: 'boolean', description: 'Remove credential references - user configures in n8n UI (default: true)' } }, returns: 'Object with workflowId, name, nodeCount, triggerType, requiredCredentials array, url, templateId, templateUrl, autoFixStatus (success/failed/skipped), and fixesApplied array', examples: [ `// Deploy template with default settings (auto-fix enabled) n8n_deploy_template({templateId: 2776})`, `// Deploy with custom name n8n_deploy_template({ templateId: 2776, name: "My Google Drive to Airtable Sync" })`, `// Deploy without auto-fix (not recommended) n8n_deploy_template({ templateId: 2776, autoFix: false })`, `// Keep original node versions (useful for compatibility) n8n_deploy_template({ templateId: 2776, autoUpgradeVersions: false })` ], useCases: [ 'Quickly deploy pre-built workflow templates', 'Set up common automation patterns', 'Bootstrap new projects with proven workflows', 'Deploy templates found via search_templates' ], performance: 'Network-dependent - Typically 300-800ms (template fetch + workflow creation + autofix)', bestPractices: [ 'Use search_templates to find templates by use case', 'Review required credentials in the response', 'Check autoFixStatus in response - "success", "failed", or "skipped"', 'Check fixesApplied in response to see what was automatically corrected', 'Configure credentials in n8n UI before activating', 'Test workflow before connecting to production systems' ], pitfalls: [ '**REQUIRES N8N_API_URL and N8N_API_KEY environment variables** - tool unavailable without n8n API access', 'Workflows created in INACTIVE state - must configure credentials and activate in n8n', 'Templates may reference services you do not have (Slack, Google, etc.)', 'Template database must be populated - run npm run fetch:templates if templates not found', 'Some issues may not be auto-fixable (e.g., missing required fields that need user input)' ], relatedTools: ['search_templates', 'get_template', 'n8n_create_workflow', 'n8n_autofix_workflow'] } };