# How to Use search_templates with Different Search Modes in n8n MCP

> Master n8n MCP's search_templates with keyword, by_nodes, by_task, and by_metadata modes. Discover targeted workflow solutions efficiently. Learn how to use this powerful tool today.

- Repository: [Romuald Członkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp)
- Tags: how-to-guide
- Published: 2026-03-24

---

**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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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.