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']
    }
  };