How to Use search_templates with Different Search Modes in n8n MCP

The search_templates tool in czlonkowski/n8n-mcp supports four distinct search modes—keyword, by_nodes, by_task, and by_metadata—each routing to specialized repository methods in TemplateRepository for targeted workflow discovery.

The search_templates function is the primary MCP (Model Context Protocol) tool for discovering n8n workflow templates in the czlonkowski/n8n-mcp repository. It enables precise template retrieval through four specialized search modes implemented across the service and repository layers. Understanding these modes allows you to filter templates by content, node types, predefined tasks, or AI-generated metadata fields.

Understanding the Four Search Modes

The TemplateService class in src/templates/template-service.ts routes incoming requests to specific repository methods based on the searchMode parameter. Each mode targets different template attributes and uses optimized database queries.

Keyword Search (Default)

Keyword search performs full-text search against template names and descriptions using SQLite FTS5, with an automatic fallback to LIKE queries when FTS5 is unavailable.

In src/templates/template-repository.ts, the searchTemplates() method handles the primary lookup, delegating to searchTemplatesLIKE() for fallback scenarios. This mode is ideal for broad discovery when you know descriptive terms but not specific implementation details.

Search by Nodes (by_nodes)

Node-based search returns templates containing specific node types (e.g., n8n-nodes-base.httpRequest). The system first normalizes node identifiers through resolveTemplateNodeTypes, then matches against the stored JSON array nodes_used using LIKE conditions.

The implementation chain flows through TemplateService.listNodeTemplates() to TemplateRepository.getTemplatesByNodes() and getNodeTemplatesCount(). Use this mode when you need workflows built with particular integration nodes.

Search by Task (by_task)

Task-based search retrieves curated template sets for predefined workflows such as "webhook_processing". The mapping between task names and relevant node types lives in TemplateRepository.getTemplatesForTask().

This mode connects to TemplateService.getTemplatesForTask() and leverages getNodeTemplatesCount() for pagination. It is optimized for high-level use cases where you know the automation goal but not the specific technical implementation.

Search by Metadata (by_metadata)

Metadata filtering targets AI-generated fields including category, complexity, setup time, required service, and target audience. The query builder buildMetadataFilterConditions() constructs dynamic SQL, executing a two-phase approach (ID retrieval first, then full row fetching) for performance optimization.

This path routes through TemplateService.searchTemplatesByMetadata() to TemplateRepository.searchTemplatesByMetadata() and getMetadataSearchCount(). Use this for finding templates matching organizational constraints like "simple setup under 30 minutes."

Practical Implementation Examples

Each search mode requires specific JSON argument structures when calling the search_templates tool from an MCP client.

Keyword Search Example

Search for chatbot-related templates using the default mode:

{
  "searchMode": "keyword",
  "query": "chatbot",
  "limit": 5
}

This executes searchTemplates() with FTS5 indexing on name and description fields.

Node-Based Search Example

Find templates using both HTTP Request and Slack nodes:

{
  "searchMode": "by_nodes",
  "nodeTypes": [
    "n8n-nodes-base.httpRequest",
    "n8n-nodes-base.slack"
  ],
  "limit": 10
}

The service calls listNodeTemplates(), which normalizes these node types and queries against the nodes_used JSON array in the database.

Task-Based Search Example

Retrieve webhook processing workflows:

{
  "searchMode": "by_task",
  "task": "webhook_processing",
  "limit": 8
}

This triggers getTemplatesForTask(), mapping the task identifier to predefined node combinations.

Metadata Filter Example

Filter for simple OpenAI templates aimed at developers:

{
  "searchMode": "by_metadata",
  "complexity": "simple",
  "requiredService": "openai",
  "maxSetupMinutes": 30,
  "targetAudience": "developers",
  "limit": 6
}

The repository builds metadata conditions and executes the two-phase query strategy.

Field-Restricted Keyword Search

Combine keyword search with field selection to minimize payload size:

{
  "searchMode": "keyword",
  "query": "automation",
  "fields": ["id", "name", "author", "metadata"],
  "limit": 4
}

The service applies formatTemplateWithFields() to return only requested properties rather than full template objects.

Architecture and Data Flow

The request routing begins in src/mcp/server.ts, where the MCP server receives the tool call and forwards parameters to TemplateService. The service layer determines which repository method to invoke based on the searchMode argument:

• keyword: searchTemplates() / getSearchCount()
• by_nodes: listNodeTemplates() → getTemplatesByNodes() / getNodeTemplatesCount()
• by_task: getTemplatesForTask() / getNodeTemplatesCount()
• by_metadata: searchTemplatesByMetadata() / getMetadataSearchCount()

All paths return a standardized paginated response containing items, total, limit, offset, and hasMore properties. The repository layer in src/templates/template-repository.ts handles the low-level SQLite operations, including JSON array parsing for node matching and conditional query building for metadata filters.

Summary

• Four distinct modes: keyword (default FTS5), by_nodes (node type matching), by_task (predefined workflow mappings), and by_metadata (AI-generated field filtering).
• Repository implementation: Core logic resides in TemplateRepository with specialized methods like getTemplatesByNodes() and searchTemplatesByMetadata().
• Performance optimization: Metadata searches use two-phase ID-first queries; keyword searches leverage FTS5 with LIKE fallback.
• Flexible output: All modes support pagination (limit/offset) and optional field restriction through formatTemplateWithFields().

Frequently Asked Questions

What is the default search mode if I don't specify searchMode?

If you omit the searchMode parameter, the tool defaults to keyword search. This performs full-text lookup against template names and descriptions using SQLite FTS5, falling back to LIKE queries if FTS5 is unavailable in the database configuration.

Can I combine multiple search modes in a single query?

No, the current implementation in src/templates/template-service.ts processes one searchMode per request. You cannot simultaneously filter by both node types and metadata fields in a single call. Execute sequential queries or post-filter results client-side if you need cross-mode filtering.

How does the by_nodes mode handle partial node type matches?

The by_nodes mode uses exact normalized matching through resolveTemplateNodeTypes followed by LIKE queries against the nodes_used JSON array. It requires complete node type identifiers (e.g., n8n-nodes-base.httpRequest) rather than partial strings, ensuring precise template retrieval for specific integration requirements.

What metadata fields are available for by_metadata searches?

Available filters include complexity (e.g., "simple", "advanced"), requiredService (e.g., "openai", "slack"), targetAudience (e.g., "developers", "marketers"), maxSetupMinutes, and category. The buildMetadataFilterConditions() method in TemplateRepository dynamically constructs SQL based on whichever combination of these fields you provide.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}