n8n-MCP

Instructions

Implementation Reference

• src/mcp/handlers-n8n-manager.ts:1632-1736 (handler)

  The main handler function that performs the n8n API health check, retrieves instance status, version information, performance metrics, and provides next steps. Handles both success and error cases with detailed responses.
  export async function handleHealthCheck(context?: InstanceContext): Promise<McpToolResponse> { const startTime = Date.now(); try { const client = ensureApiConfigured(context); const health = await client.healthCheck(); // Get MCP version from package.json const packageJson = require('../../package.json'); const mcpVersion = packageJson.version; const supportedN8nVersion = packageJson.dependencies?.n8n?.replace(/[^0-9.]/g, ''); // Check npm for latest version (async, non-blocking) const versionCheck = await checkNpmVersion(); // Get cache metrics for performance monitoring const cacheMetricsData = getInstanceCacheMetrics(); // Calculate response time const responseTime = Date.now() - startTime; // Build response data const responseData: HealthCheckResponseData = { status: health.status, instanceId: health.instanceId, n8nVersion: health.n8nVersion, features: health.features, apiUrl: getN8nApiConfig()?.baseUrl, mcpVersion, supportedN8nVersion, versionCheck: { current: versionCheck.currentVersion, latest: versionCheck.latestVersion, upToDate: !versionCheck.isOutdated, message: formatVersionMessage(versionCheck), ...(versionCheck.updateCommand ? { updateCommand: versionCheck.updateCommand } : {}) }, performance: { responseTimeMs: responseTime, cacheHitRate: (cacheMetricsData.hits + cacheMetricsData.misses) > 0 ? ((cacheMetricsData.hits / (cacheMetricsData.hits + cacheMetricsData.misses)) * 100).toFixed(2) + '%' : 'N/A', cachedInstances: cacheMetricsData.size } }; // Add next steps guidance based on telemetry insights responseData.nextSteps = [ '• Create workflow: n8n_create_workflow', '• List workflows: n8n_list_workflows', '• Search nodes: search_nodes', '• Browse templates: search_templates' ]; // Add update warning if outdated if (versionCheck.isOutdated && versionCheck.latestVersion) { responseData.updateWarning = `⚠️ n8n-mcp v${versionCheck.latestVersion} is available (you have v${versionCheck.currentVersion}). Update recommended.`; } // Track result in telemetry telemetry.trackEvent('health_check_completed', { success: true, responseTimeMs: responseTime, upToDate: !versionCheck.isOutdated, apiConnected: true }); return { success: true, data: responseData }; } catch (error) { const responseTime = Date.now() - startTime; // Track failure in telemetry telemetry.trackEvent('health_check_failed', { success: false, responseTimeMs: responseTime, errorType: error instanceof N8nApiError ? error.code : 'unknown' }); if (error instanceof N8nApiError) { return { success: false, error: getUserFriendlyErrorMessage(error), code: error.code, details: { apiUrl: getN8nApiConfig()?.baseUrl, hint: 'Check if n8n is running and API is enabled', troubleshooting: [ '1. Verify n8n instance is running', '2. Check N8N_API_URL is correct', '3. Verify N8N_API_KEY has proper permissions', '4. Run n8n_health_check with mode="diagnostic" for detailed analysis' ] } }; } return { success: false, error: error instanceof Error ? error.message : 'Unknown error occurred' }; } }
• src/mcp/tools-n8n-manager.ts:417-435 (schema)

  Tool definition including name, description, and input schema specifying parameters for mode ('status' or 'diagnostic') and verbose flag.
  { name: 'n8n_health_check', description: `Check n8n instance health and API connectivity. Use mode='diagnostic' for detailed troubleshooting with env vars and tool status.`, inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['status', 'diagnostic'], description: 'Mode: "status" (default) for quick health check, "diagnostic" for detailed debug info including env vars and tool status', default: 'status' }, verbose: { type: 'boolean', description: 'Include extra details in diagnostic mode (default: false)' } } } },
• src/mcp/tool-docs/system/n8n-health-check.ts:1-100 (helper)

  Detailed tool documentation including parameters, return types, examples, use cases, best practices, pitfalls, and related tools for the n8n_health_check tool.
  import { ToolDocumentation } from '../types'; export const n8nHealthCheckDoc: ToolDocumentation = { name: 'n8n_health_check', category: 'system', essentials: { description: 'Check n8n instance health, API connectivity, version status, and performance metrics', keyParameters: ['mode', 'verbose'], example: 'n8n_health_check({mode: "status"})', performance: 'Fast - single API call (~150-200ms median)', tips: [ 'Use before starting workflow operations to ensure n8n is responsive', 'Automatically checks if n8n-mcp version is outdated', 'Returns version info, performance metrics, and next-step recommendations', 'New: Shows cache hit rate and response time for performance monitoring' ] }, full: { description: `Performs a comprehensive health check of the configured n8n instance through its API. This tool verifies: - API endpoint accessibility and response time - n8n instance version and build information - Authentication status and permissions - Available features and enterprise capabilities - Database connectivity (as reported by n8n) - Queue system status (if configured) Health checks are crucial for: - Monitoring n8n instance availability - Detecting performance degradation - Verifying API compatibility before operations - Ensuring authentication is working correctly`, parameters: { mode: { type: 'string', required: false, description: 'Operation mode: "status" (default) for quick health check, "diagnostic" for detailed debug info including env vars and tool status', default: 'status', enum: ['status', 'diagnostic'] }, verbose: { type: 'boolean', required: false, description: 'Include extra details in diagnostic mode', default: false } }, returns: `Health status object containing: - status: Overall health status ('healthy', 'degraded', 'error') - n8nVersion: n8n instance version information - instanceId: Unique identifier for the n8n instance - features: Object listing available features and their status - mcpVersion: Current n8n-mcp version - supportedN8nVersion: Recommended n8n version for compatibility - versionCheck: Version status information - current: Current n8n-mcp version - latest: Latest available version from npm - upToDate: Boolean indicating if version is current - message: Formatted version status message - updateCommand: Command to update (if outdated) - performance: Performance metrics - responseTimeMs: API response time in milliseconds - cacheHitRate: Cache efficiency percentage - cachedInstances: Number of cached API instances - nextSteps: Recommended actions after health check - updateWarning: Warning if version is outdated (if applicable)`, examples: [ 'n8n_health_check({}) - Complete health check with version and performance data', '// Use in monitoring scripts\nconst health = await n8n_health_check({});\nif (health.status !== "ok") alert("n8n is down!");\nif (!health.versionCheck.upToDate) console.log("Update available:", health.versionCheck.updateCommand);', '// Check before critical operations\nconst health = await n8n_health_check({});\nif (health.performance.responseTimeMs > 1000) console.warn("n8n is slow");\nif (health.versionCheck.isOutdated) console.log(health.updateWarning);' ], useCases: [ 'Pre-flight checks before workflow deployments', 'Continuous monitoring of n8n instance health', 'Troubleshooting connectivity or performance issues', 'Verifying n8n version compatibility with workflows', 'Detecting feature availability (enterprise features, queue mode, etc.)' ], performance: `Fast response expected: - Single HTTP request to /health endpoint - Typically responds in <100ms for healthy instances - Timeout after 10 seconds indicates severe issues - Minimal server load - safe for frequent polling`, bestPractices: [ 'Run health checks before batch operations or deployments', 'Set up automated monitoring with regular health checks', 'Log response times to detect performance trends', 'Check version compatibility when deploying workflows', 'Use health status to implement circuit breaker patterns' ], pitfalls: [ 'Requires N8N_API_URL and N8N_API_KEY to be configured', 'Network issues may cause false negatives', 'Does not check individual workflow health', 'Health endpoint might be cached - not real-time for all metrics' ], relatedTools: ['n8n_list_workflows', 'n8n_validate_workflow', 'n8n_workflow_versions'] } };