n8n-MCP

Instructions

Implementation Reference

• src/mcp/tools-documentation.ts:3-66 (handler)

  Core handler logic for tools_documentation tool. Retrieves and formats documentation for specific tools or special guides based on topic and depth parameters.
  export function getToolDocumentation(toolName: string, depth: 'essentials' | 'full' = 'essentials'): string { // Check for special documentation topics if (toolName === 'javascript_code_node_guide') { return getJavaScriptCodeNodeGuide(depth); } if (toolName === 'python_code_node_guide') { return getPythonCodeNodeGuide(depth); } const tool = toolsDocumentation[toolName]; if (!tool) { return `Tool '${toolName}' not found. Use tools_documentation() to see available tools.`; } if (depth === 'essentials') { const { essentials } = tool; return `# ${tool.name} ${essentials.description} **Example**: ${essentials.example} **Key parameters**: ${essentials.keyParameters.join(', ')} **Performance**: ${essentials.performance} **Tips**: ${essentials.tips.map(tip => `- ${tip}`).join('\n')} For full documentation, use: tools_documentation({topic: "${toolName}", depth: "full"})`; } // Full documentation const { full } = tool; return `# ${tool.name} ${full.description} ## Parameters ${Object.entries(full.parameters).map(([param, info]) => `- **${param}** (${info.type}${info.required ? ', required' : ''}): ${info.description}` ).join('\n')} ## Returns ${full.returns} ## Examples ${full.examples.map(ex => `\`\`\`javascript\n${ex}\n\`\`\``).join('\n\n')} ## Common Use Cases ${full.useCases.map(uc => `- ${uc}`).join('\n')} ## Performance ${full.performance} ## Best Practices ${full.bestPractices.map(bp => `- ${bp}`).join('\n')} ## Common Pitfalls ${full.pitfalls.map(p => `- ${p}`).join('\n')} ## Related Tools ${full.relatedTools.map(t => `- ${t}`).join('\n')}`; }
• src/mcp/tools-documentation.ts:68-186 (handler)

  Handler for overview mode of tools_documentation. Returns comprehensive list of all available tools, categories, usage patterns, and performance info.
  export function getToolsOverview(depth: 'essentials' | 'full' = 'essentials'): string { // Get version info from package.json const packageJson = require('../../package.json'); const supportedN8nVersion = packageJson.dependencies?.n8n?.replace(/[^0-9.]/g, '') || 'latest'; if (depth === 'essentials') { return `# n8n MCP Tools Reference ## Important: Compatibility Notice ⚠️ This MCP server is tested with n8n version ${supportedN8nVersion}. Inform the user to check their n8n version matches or is compatible with the supported version listed above. ## Code Node Configuration When working with Code nodes, always start by calling the relevant guide: - tools_documentation({topic: "javascript_code_node_guide"}) for JavaScript Code nodes - tools_documentation({topic: "python_code_node_guide"}) for Python Code nodes ## Standard Workflow Pattern ⚠️ **CRITICAL**: Always call get_node() with detail='standard' FIRST before configuring any node! 1. **Find** the node you need: - search_nodes({query: "slack"}) - Search by keyword - search_nodes({query: "communication"}) - Search by category name - search_nodes({query: "AI langchain"}) - Search for AI-capable nodes 2. **Configure** the node (ALWAYS START WITH STANDARD DETAIL): - ✅ get_node({nodeType: "nodes-base.slack", detail: "standard"}) - Get essential properties FIRST (~1-2KB, shows required fields) - get_node({nodeType: "nodes-base.slack", detail: "full"}) - Get complete schema only if standard insufficient (~100KB+) - get_node({nodeType: "nodes-base.slack", mode: "docs"}) - Get readable markdown documentation - get_node({nodeType: "nodes-base.slack", mode: "search_properties", propertyQuery: "auth"}) - Find specific properties 3. **Validate** before deployment: - validate_node({nodeType: "nodes-base.slack", config: {...}, mode: "minimal"}) - Quick required fields check - validate_node({nodeType: "nodes-base.slack", config: {...}}) - Full validation with errors/warnings/suggestions - validate_workflow({workflow: {...}}) - Validate entire workflow ## Tool Categories (19 Tools Total) **Discovery Tools** (1 tool) - search_nodes - Full-text search across all nodes (supports OR, AND, FUZZY modes) **Configuration Tools** (1 consolidated tool) - get_node - Unified node information tool: - detail='minimal'/'standard'/'full': Progressive detail levels - mode='docs': Readable markdown documentation - mode='search_properties': Find specific properties - mode='versions'/'compare'/'breaking'/'migrations': Version management **Validation Tools** (2 tools) - validate_node - Unified validation with mode='full' or mode='minimal' - validate_workflow - Complete workflow validation (nodes, connections, expressions) **Template Tools** (2 tools) - get_template - Get complete workflow JSON by ID - search_templates - Unified template search: - searchMode='keyword': Text search (default) - searchMode='by_nodes': Find templates using specific nodes - searchMode='by_task': Curated task-based templates - searchMode='by_metadata': Filter by complexity/services **n8n API Tools** (13 tools, requires N8N_API_URL configuration) - n8n_create_workflow - Create new workflows - n8n_get_workflow - Get workflow with mode='full'/'details'/'structure'/'minimal' - n8n_update_full_workflow - Full workflow replacement - n8n_update_partial_workflow - Incremental diff-based updates - n8n_delete_workflow - Delete workflow - n8n_list_workflows - List workflows with filters - n8n_validate_workflow - Validate workflow by ID - n8n_autofix_workflow - Auto-fix common issues - n8n_test_workflow - Test/trigger workflows (webhook, form, chat, execute) - n8n_executions - Unified execution management (action='get'/'list'/'delete') - n8n_health_check - Check n8n API connectivity - n8n_workflow_versions - Version history and rollback - n8n_deploy_template - Deploy templates directly to n8n instance ## Performance Characteristics - Instant (<10ms): search_nodes, get_node (minimal/standard) - Fast (<100ms): validate_node, get_template - Moderate (100-500ms): validate_workflow, get_node (full detail) - Network-dependent: All n8n_* tools For comprehensive documentation on any tool: tools_documentation({topic: "tool_name", depth: "full"})`; } const categories = getAllCategories(); return `# n8n MCP Tools - Complete Reference ## Important: Compatibility Notice ⚠️ This MCP server is tested with n8n version ${supportedN8nVersion}. Run n8n_health_check() to verify your n8n instance compatibility and API connectivity. ## Code Node Guides For Code node configuration, use these comprehensive guides: - tools_documentation({topic: "javascript_code_node_guide", depth: "full"}) - JavaScript patterns, n8n variables, error handling - tools_documentation({topic: "python_code_node_guide", depth: "full"}) - Python patterns, data access, debugging ## All Available Tools by Category ${categories.map(cat => { const tools = getToolsByCategory(cat); const categoryName = cat.charAt(0).toUpperCase() + cat.slice(1).replace('_', ' '); return `### ${categoryName} ${tools.map(toolName => { const tool = toolsDocumentation[toolName]; return `- **${toolName}**: ${tool.essentials.description}`; }).join('\n')}`; }).join('\n\n')} ## Usage Notes - All node types require the "nodes-base." or "nodes-langchain." prefix - Use get_node() with detail='standard' first for most tasks (~95% smaller than detail='full') - Validation profiles: minimal (editing), runtime (default), strict (deployment) - n8n API tools only available when N8N_API_URL and N8N_API_KEY are configured For detailed documentation on any tool: tools_documentation({topic: "tool_name", depth: "full"})`; }
• src/mcp/tool-docs/system/tools-documentation.ts:3-63 (schema)

  Detailed schema and documentation definition for the tools_documentation tool, used by the handler to generate responses.
  export const toolsDocumentationDoc: ToolDocumentation = { name: 'tools_documentation', category: 'system', essentials: { description: 'The meta-documentation tool. Returns documentation for any MCP tool, including itself. Call without parameters for a comprehensive overview of all available tools. This is your starting point for discovering n8n MCP capabilities.', keyParameters: ['topic', 'depth'], example: 'tools_documentation({topic: "search_nodes"})', performance: 'Instant (static content)', tips: [ 'Call without parameters first to see all tools', 'Can document itself: tools_documentation({topic: "tools_documentation"})', 'Use depth:"full" for comprehensive details' ] }, full: { description: 'The self-referential documentation system for all MCP tools. This tool can document any other tool, including itself. It\'s the primary discovery mechanism for understanding what tools are available and how to use them. Returns utilitarian documentation optimized for AI agent consumption.', parameters: { topic: { type: 'string', description: 'Tool name (e.g., "search_nodes"), special topic ("javascript_code_node_guide", "python_code_node_guide"), or "overview". Leave empty for quick reference.', required: false }, depth: { type: 'string', description: 'Level of detail: "essentials" (default, concise) or "full" (comprehensive with examples)', required: false } }, returns: 'Markdown-formatted documentation tailored for the requested tool and depth. For essentials: key info, parameters, example, tips. For full: complete details, all examples, use cases, best practices.', examples: [ '// Get started - see all available tools', 'tools_documentation()', '', '// Learn about a specific tool', 'tools_documentation({topic: "search_nodes"})', '', '// Get comprehensive details', 'tools_documentation({topic: "validate_workflow", depth: "full"})', '', '// Self-referential example - document this tool', 'tools_documentation({topic: "tools_documentation", depth: "full"})', '', '// Code node guides', 'tools_documentation({topic: "javascript_code_node_guide"})', 'tools_documentation({topic: "python_code_node_guide"})' ], useCases: [ 'Initial discovery of available MCP tools', 'Learning how to use specific tools', 'Finding required and optional parameters', 'Getting working examples to copy', 'Understanding tool performance characteristics', 'Discovering related tools for workflows' ], performance: 'Instant - all documentation is pre-loaded in memory', bestPractices: [ 'Always start with tools_documentation() to see available tools', 'Use essentials for quick parameter reference during coding', 'Switch to full depth when debugging or learning new tools', 'Check Code node guides when working with Code nodes' ], pitfalls: [ 'Tool names must match exactly - use the overview to find correct names', 'Not all internal functions are documented', 'Special topics (code guides) require exact names' ], relatedTools: ['n8n_health_check for verifying API connection', 'search_templates for workflow examples', 'search_nodes for finding nodes'] } };
• src/mcp/tools.ts:10-28 (registration)

  MCP tool registration definition including name, description, and input schema for tools_documentation.
  { name: 'tools_documentation', description: `Get documentation for n8n MCP tools. Call without parameters for quick start guide. Use topic parameter to get documentation for specific tools. Use depth='full' for comprehensive documentation.`, inputSchema: { type: 'object', properties: { topic: { type: 'string', description: 'Tool name (e.g., "search_nodes") or "overview" for general guide. Leave empty for quick reference.', }, depth: { type: 'string', enum: ['essentials', 'full'], description: 'Level of detail. "essentials" (default) for quick reference, "full" for comprehensive docs.', default: 'essentials', }, }, }, },
• src/mcp/tool-docs/index.ts:29-64 (helper)

  Aggregation of all tool documentation objects, providing the data source for tools_documentation handler.
  export const toolsDocumentation: Record<string, ToolDocumentation> = { // System tools tools_documentation: toolsDocumentationDoc, n8n_health_check: n8nHealthCheckDoc, // Guides ai_agents_guide: aiAgentsGuide, // Discovery tools search_nodes: searchNodesDoc, // Configuration tools get_node: getNodeDoc, // Validation tools validate_node: validateNodeDoc, validate_workflow: validateWorkflowDoc, // Template tools get_template: getTemplateDoc, search_templates: searchTemplatesDoc, // Workflow Management tools (n8n API) n8n_create_workflow: n8nCreateWorkflowDoc, n8n_get_workflow: n8nGetWorkflowDoc, n8n_update_full_workflow: n8nUpdateFullWorkflowDoc, n8n_update_partial_workflow: n8nUpdatePartialWorkflowDoc, n8n_delete_workflow: n8nDeleteWorkflowDoc, n8n_list_workflows: n8nListWorkflowsDoc, n8n_validate_workflow: n8nValidateWorkflowDoc, n8n_autofix_workflow: n8nAutofixWorkflowDoc, n8n_test_workflow: n8nTestWorkflowDoc, n8n_executions: n8nExecutionsDoc, n8n_workflow_versions: n8nWorkflowVersionsDoc, n8n_deploy_template: n8nDeployTemplateDoc };