n8n-MCP

Instructions

Implementation Reference

• dist/mcp/tools.js:207-296 (schema)

  Primary input/output schema definition for the search_templates MCP tool, including all parameters and validation rules.

  {
      name: 'search_templates',
      description: `Search templates with multiple modes. Use searchMode='keyword' for text search, 'by_nodes' to find templates using specific nodes, 'by_task' for curated task-based templates, 'by_metadata' for filtering by complexity/setup time/services.`,
      inputSchema: {
          type: 'object',
          properties: {
              searchMode: {
                  type: 'string',
                  enum: ['keyword', 'by_nodes', 'by_task', 'by_metadata'],
                  description: 'Search mode. keyword=text search (default), by_nodes=find by node types, by_task=curated task templates, by_metadata=filter by complexity/services',
                  default: 'keyword',
              },
              query: {
                  type: 'string',
                  description: 'For searchMode=keyword: search keyword (e.g., "chatbot")',
              },
              fields: {
                  type: 'array',
                  items: {
                      type: 'string',
                      enum: ['id', 'name', 'description', 'author', 'nodes', 'views', 'created', 'url', 'metadata'],
                  },
                  description: 'For searchMode=keyword: fields to include in response. Default: all fields.',
              },
              nodeTypes: {
                  type: 'array',
                  items: { type: 'string' },
                  description: 'For searchMode=by_nodes: array of node types (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"])',
              },
              task: {
                  type: 'string',
                  enum: [
                      'ai_automation',
                      'data_sync',
                      'webhook_processing',
                      'email_automation',
                      'slack_integration',
                      'data_transformation',
                      'file_processing',
                      'scheduling',
                      'api_integration',
                      'database_operations'
                  ],
                  description: 'For searchMode=by_task: the type of task',
              },
              category: {
                  type: 'string',
                  description: 'For searchMode=by_metadata: filter by category (e.g., "automation", "integration")',
              },
              complexity: {
                  type: 'string',
                  enum: ['simple', 'medium', 'complex'],
                  description: 'For searchMode=by_metadata: filter by complexity level',
              },
              maxSetupMinutes: {
                  type: 'number',
                  description: 'For searchMode=by_metadata: maximum setup time in minutes',
                  minimum: 5,
                  maximum: 480,
              },
              minSetupMinutes: {
                  type: 'number',
                  description: 'For searchMode=by_metadata: minimum setup time in minutes',
                  minimum: 5,
                  maximum: 480,
              },
              requiredService: {
                  type: 'string',
                  description: 'For searchMode=by_metadata: filter by required service (e.g., "openai", "slack")',
              },
              targetAudience: {
                  type: 'string',
                  description: 'For searchMode=by_metadata: filter by target audience (e.g., "developers", "marketers")',
              },
              limit: {
                  type: 'number',
                  description: 'Maximum number of results. Default 20.',
                  default: 20,
                  minimum: 1,
                  maximum: 100,
              },
              offset: {
                  type: 'number',
                  description: 'Pagination offset. Default 0.',
                  default: 0,
                  minimum: 0,
              },
          },
      },
  },

• src/mcp/tool-docs/templates/search-templates.ts:1-141 (schema)

  Detailed documentation object for search_templates tool, used by tools_documentation tool to provide usage examples and parameter descriptions.

  import { ToolDocumentation } from '../types';
  
  export const searchTemplatesDoc: ToolDocumentation = {
    name: 'search_templates',
    category: 'templates',
    essentials: {
      description: 'Unified template search with multiple modes: keyword search, by node types, by task type, or by metadata. 2,700+ templates available.',
      keyParameters: ['searchMode', 'query', 'nodeTypes', 'task', 'limit'],
      example: 'search_templates({searchMode: "by_task", task: "webhook_processing"})',
      performance: 'Fast (<100ms) - FTS5 full-text search',
      tips: [
        'searchMode="keyword" (default): Search by name/description',
        'searchMode="by_nodes": Find templates using specific nodes',
        'searchMode="by_task": Get curated templates for common tasks',
        'searchMode="by_metadata": Filter by complexity, services, audience'
      ]
    },
    full: {
      description: `**Search Modes:**
  - keyword (default): Full-text search across template names and descriptions
  - by_nodes: Find templates that use specific node types
  - by_task: Get curated templates for predefined task categories
  - by_metadata: Filter by complexity, setup time, required services, or target audience
  
  **Available Task Types (for searchMode="by_task"):**
  ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations`,
      parameters: {
        searchMode: {
          type: 'string',
          required: false,
          description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata"'
        },
        query: {
          type: 'string',
          required: false,
          description: 'For searchMode=keyword: Search keywords (e.g., "chatbot", "automation")'
        },
        nodeTypes: {
          type: 'array',
          required: false,
          description: 'For searchMode=by_nodes: Array of node types (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"])'
        },
        task: {
          type: 'string',
          required: false,
          description: 'For searchMode=by_task: Task type (ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations)'
        },
        complexity: {
          type: 'string',
          required: false,
          description: 'For searchMode=by_metadata: Filter by complexity ("simple", "medium", "complex")'
        },
        maxSetupMinutes: {
          type: 'number',
          required: false,
          description: 'For searchMode=by_metadata: Maximum setup time in minutes (5-480)'
        },
        minSetupMinutes: {
          type: 'number',
          required: false,
          description: 'For searchMode=by_metadata: Minimum setup time in minutes (5-480)'
        },
        requiredService: {
          type: 'string',
          required: false,
          description: 'For searchMode=by_metadata: Filter by required service (e.g., "openai", "slack", "google")'
        },
        targetAudience: {
          type: 'string',
          required: false,
          description: 'For searchMode=by_metadata: Filter by target audience (e.g., "developers", "marketers")'
        },
        category: {
          type: 'string',
          required: false,
          description: 'For searchMode=by_metadata: Filter by category (e.g., "automation", "integration")'
        },
        fields: {
          type: 'array',
          required: false,
          description: 'For searchMode=keyword: Fields to include (id, name, description, author, nodes, views, created, url, metadata)'
        },
        limit: {
          type: 'number',
          required: false,
          description: 'Maximum results (default 20, max 100)'
        },
        offset: {
          type: 'number',
          required: false,
          description: 'Pagination offset (default 0)'
        }
      },
      returns: `Returns an object containing:
  - templates: Array of matching templates
    - id: Template ID for get_template()
    - name: Template name
    - description: What the workflow does
    - author: Creator information
    - nodes: Array of node types used
    - views: Popularity metric
    - created: Creation date
    - url: Link to template
    - metadata: AI-generated metadata (complexity, services, etc.)
  - totalFound: Total matching templates
  - searchMode: The mode used`,
      examples: [
        '// Keyword search (default)\nsearch_templates({query: "chatbot"})',
        '// Find templates using specific nodes\nsearch_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]})',
        '// Get templates for a task type\nsearch_templates({searchMode: "by_task", task: "webhook_processing"})',
        '// Filter by metadata\nsearch_templates({searchMode: "by_metadata", complexity: "simple", requiredService: "openai"})',
        '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})'
      ],
      useCases: [
        'Find workflows by business purpose (keyword search)',
        'Find templates using specific integrations (by_nodes)',
        'Get pre-built solutions for common tasks (by_task)',
        'Filter by complexity for team skill level (by_metadata)',
        'Find templates requiring specific services (by_metadata)'
      ],
      performance: `Fast performance across all modes:
  - keyword: <50ms with FTS5 indexing
  - by_nodes: <100ms with indexed lookups
  - by_task: <50ms from curated cache
  - by_metadata: <100ms with filtered queries`,
      bestPractices: [
        'Use searchMode="by_task" for common automation patterns',
        'Use searchMode="by_nodes" when you know which integrations you need',
        'Use searchMode="keyword" for general discovery',
        'Combine by_metadata filters for precise matching',
        'Use get_template(id) to get the full workflow JSON'
      ],
      pitfalls: [
        'searchMode="keyword" searches names/descriptions, not node types',
        'by_nodes requires full node type with prefix (n8n-nodes-base.xxx)',
        'by_metadata filters may return fewer results',
        'Not all templates have complete metadata'
      ],
      relatedTools: ['get_template', 'search_nodes', 'validate_workflow']
    }
  };

• dist/templates/template-service.js:88-101 (handler)

  Core handler logic for keyword-based template search, delegating to repository and formatting results with pagination.

  async searchTemplates(query, limit = 20, offset = 0, fields) {
      const templates = this.repository.searchTemplates(query, limit, offset);
      const total = this.repository.getSearchCount(query);
      const items = fields
          ? templates.map(t => this.formatTemplateWithFields(t, fields))
          : templates.map(t => this.formatTemplateInfo(t));
      return {
          items,
          total,
          limit,
          offset,
          hasMore: offset + limit < total
      };
  }

• dist/templates/template-repository.js:226-237 (helper)

  Fallback LIKE-based search implementation for templates when FTS5 is unavailable.

  searchTemplatesLIKE(query, limit = 20, offset = 0) {
      const likeQuery = `%${query}%`;
      logger_1.logger.debug(`Using LIKE search with pattern: ${likeQuery}`);
      const results = this.db.prepare(`
    SELECT * FROM templates 
    WHERE name LIKE ? OR description LIKE ?
    ORDER BY views DESC, created_at DESC
    LIMIT ? OFFSET ?
  `).all(likeQuery, likeQuery, limit, offset);
      logger_1.logger.debug(`LIKE search returned ${results.length} results`);
      return results.map(t => this.decompressWorkflow(t));
  }

• dist/templates/template-repository.js:493-541 (helper)

  Advanced metadata-based search using JSON queries on template metadata, with optimization for ordering and pagination.

  searchTemplatesByMetadata(filters, limit = 20, offset = 0) {
      const startTime = Date.now();
      const { conditions, params } = this.buildMetadataFilterConditions(filters);
      const idsQuery = `
    SELECT id FROM templates
    WHERE ${conditions.join(' AND ')}
    ORDER BY views DESC, created_at DESC, id ASC
    LIMIT ? OFFSET ?
  `;
      params.push(limit, offset);
      const ids = this.db.prepare(idsQuery).all(...params);
      const phase1Time = Date.now() - startTime;
      if (ids.length === 0) {
          logger_1.logger.debug('Metadata search found 0 results', { filters, phase1Ms: phase1Time });
          return [];
      }
      const idValues = ids.map(r => r.id).filter(id => typeof id === 'number' && id > 0 && Number.isInteger(id));
      if (idValues.length === 0) {
          logger_1.logger.warn('No valid IDs after filtering', { filters, originalCount: ids.length });
          return [];
      }
      if (idValues.length !== ids.length) {
          logger_1.logger.warn('Some IDs were filtered out as invalid', {
              original: ids.length,
              valid: idValues.length,
              filtered: ids.length - idValues.length
          });
      }
      const phase2Start = Date.now();
      const orderedQuery = `
    WITH ordered_ids(id, sort_order) AS (
      VALUES ${idValues.map((id, idx) => `(${id}, ${idx})`).join(', ')}
    )
    SELECT t.* FROM templates t
    INNER JOIN ordered_ids o ON t.id = o.id
    ORDER BY o.sort_order
  `;
      const results = this.db.prepare(orderedQuery).all();
      const phase2Time = Date.now() - phase2Start;
      logger_1.logger.debug(`Metadata search found ${results.length} results`, {
          filters,
          count: results.length,
          phase1Ms: phase1Time,
          phase2Ms: phase2Time,
          totalMs: Date.now() - startTime,
          optimization: 'two-phase-with-ordering'
      });
      return results.map(t => this.decompressWorkflow(t));
  }