n8n-MCP

Instructions

Implementation Reference

• src/mcp/tools.ts:30-58 (schema)

  Tool schema definition including input schema, description, parameters, and requirements for the 'search_nodes' tool
  name: 'search_nodes', description: `Search n8n nodes by keyword with optional real-world examples. Pass query as string. Example: query="webhook" or query="database". Returns max 20 results. Use includeExamples=true to get top 2 template configs per node.`, inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search terms. Use quotes for exact phrase.', }, limit: { type: 'number', description: 'Max results (default 20)', default: 20, }, mode: { type: 'string', enum: ['OR', 'AND', 'FUZZY'], description: 'OR=any word, AND=all words, FUZZY=typo-tolerant', default: 'OR', }, includeExamples: { type: 'boolean', description: 'Include top 2 real-world configuration examples from popular templates (default: false)', default: false, }, }, required: ['query'], }, },
• src/mcp-tools-engine.ts:22-25 (handler)

  Main handler function for search_nodes tool, delegates to NodeRepository.searchNodes with defaults
  async searchNodes(args: any) { return this.repository.searchNodes(args.query, args.mode || 'OR', args.limit || 20); }
• src/database/node-repository.ts:142-180 (helper)

  Core search implementation using SQLite LIKE queries for different modes (OR, AND, FUZZY). FTS5 used in production MCP server.
  searchNodes(query: string, mode: 'OR' | 'AND' | 'FUZZY' = 'OR', limit: number = 20): any[] { let sql = ''; const params: any[] = []; if (mode === 'FUZZY') { // Simple fuzzy search sql = ` SELECT * FROM nodes WHERE node_type LIKE ? OR display_name LIKE ? OR description LIKE ? ORDER BY display_name LIMIT ? `; const fuzzyQuery = `%${query}%`; params.push(fuzzyQuery, fuzzyQuery, fuzzyQuery, limit); } else { // OR/AND mode const words = query.split(/\s+/).filter(w => w.length > 0); const conditions = words.map(() => '(node_type LIKE ? OR display_name LIKE ? OR description LIKE ?)' ); const operator = mode === 'AND' ? ' AND ' : ' OR '; sql = ` SELECT * FROM nodes WHERE ${conditions.join(operator)} ORDER BY display_name LIMIT ? `; for (const word of words) { const searchTerm = `%${word}%`; params.push(searchTerm, searchTerm, searchTerm); } params.push(limit); } const rows = this.db.prepare(sql).all(...params) as any[]; return rows.map(row => this.parseNodeRow(row)); }
• src/mcp/tool-docs/discovery/search-nodes.ts:3-54 (schema)

  Detailed tool documentation and schema used for tools_documentation tool responses.
  export const searchNodesDoc: ToolDocumentation = { name: 'search_nodes', category: 'discovery', essentials: { description: 'Text search across node names and descriptions. Returns most relevant nodes first, with frequently-used nodes (HTTP Request, Webhook, Set, Code, Slack) prioritized in results. Searches all 500+ nodes in the database.', keyParameters: ['query', 'mode', 'limit'], example: 'search_nodes({query: "webhook"})', performance: '<20ms even for complex queries', tips: [ 'OR mode (default): Matches any search word', 'AND mode: Requires all words present', 'FUZZY mode: Handles typos and spelling errors', 'Use quotes for exact phrases: "google sheets"' ] }, full: { description: 'Full-text search engine for n8n nodes using SQLite FTS5. Searches across node names, descriptions, and aliases. Results are ranked by relevance with commonly-used nodes given priority. Common nodes include: HTTP Request, Webhook, Set, Code, IF, Switch, Merge, SplitInBatches, Slack, Google Sheets.', parameters: { query: { type: 'string', description: 'Search keywords. Use quotes for exact phrases like "google sheets"', required: true }, limit: { type: 'number', description: 'Maximum results to return. Default: 20, Max: 100', required: false }, mode: { type: 'string', description: 'Search mode: "OR" (any word matches, default), "AND" (all words required), "FUZZY" (typo-tolerant)', required: false } }, returns: 'Array of node objects sorted by relevance score. Each object contains: nodeType, displayName, description, category, relevance score. Common nodes appear first when relevance is similar.', examples: [ 'search_nodes({query: "webhook"}) - Returns Webhook node as top result', 'search_nodes({query: "database"}) - Returns MySQL, Postgres, MongoDB, Redis, etc.', 'search_nodes({query: "google sheets", mode: "AND"}) - Requires both words', 'search_nodes({query: "slak", mode: "FUZZY"}) - Finds Slack despite typo', 'search_nodes({query: "http api"}) - Finds HTTP Request, GraphQL, REST nodes', 'search_nodes({query: "transform data"}) - Finds Set, Code, Function, Item Lists nodes' ], useCases: [ 'Finding nodes when you know partial names', 'Discovering nodes by functionality (e.g., "email", "database", "transform")', 'Handling user typos in node names', 'Finding all nodes related to a service (e.g., "google", "aws", "microsoft")' ], performance: '<20ms for simple queries, <50ms for complex FUZZY searches. Uses FTS5 index for speed', bestPractices: [ 'Start with single keywords for broadest results', 'Use FUZZY mode when users might misspell node names', 'AND mode works best for 2-3 word searches', 'Combine with get_node after finding the right node' ], pitfalls: [ 'AND mode searches all fields (name, description) not just node names', 'FUZZY mode with very short queries (1-2 chars) may return unexpected results', 'Exact matches in quotes are case-sensitive' ], relatedTools: ['get_node to configure found nodes', 'search_templates to find workflow examples', 'validate_node to check configurations'] } };