@catalogicus-international/n8n-nodes-meilisearch

Community nodes for Meilisearch in n8n 2.x. The package targets Meilisearch v1.53.1 and Node.js 24.

Nodes

• Meilisearch (meilisearch) provides ergonomic operations for common workflows, a typed catalog for every stable v1.53.1 endpoint, and a host-bound Raw API Request for experimental, enterprise, or future routes.
• Meilisearch Tool (meilisearchTool) exposes a deliberately restricted surface to n8n AI Agent.

Connect Meilisearch Tool to the Tools input of either the standard n8n AI Agent
or the root GigaChat AI node from n8n-nodes-gigachat:

Meilisearch Tool ──ai_tool──> GigaChat AI (Tools)

Do not connect it to the deprecated GigaChat Model node, which does not provide the
AI Agent Tools interface. Select the permitted operation in the Meilisearch Tool UI;
the agent then supplies only the arguments declared for that operation, such as the
index UID, document or task ID, request object, or documents array.

Credentials use type meilisearchApi and display name Meilisearch API. Set Host URL (for example http://localhost:7700) and, when the server is protected, API Key. The credential test normalizes the URL and calls /version.

Workflow behavior

Document writes accept the current item, all input items as one batch, a JSON object/array, or a binary JSON/NDJSON/CSV file. Async writes can wait for task completion with configurable interval, timeout, and exponential backoff. Failed tasks throw unless Return Failed Task is enabled.

List operations preserve the Meilisearch envelope by default. Return All follows offset or cursor pagination. Split Into Items emits each results entry with input pairing and can attach metadata to every item or emit one summary item.

For the named Search operation, enable Use Semantic Search, select a configured Embedder, and set Semantic Ratio from 0 (keyword only) to 1 (semantic only). The default ratio is 0.5. When enabled, these fields replace hybrid from Body (JSON); when disabled, a manually supplied hybrid object remains unchanged. Meilisearch performs the embedding and hybrid search.

Destructive workflow operations require Confirm Destructive Operation. Raw requests accept only paths beginning with a single / on the configured host and reject Authorization and Host overrides. Streams default to at most 100 events or 60 seconds.

The AI Tool permits search, multi-search, facet search, similar documents, read-only document/index/settings/stats/task/system operations, and add-or-update/add-or-replace document writes. It has no raw, key, settings-write, delete, backup, webhook, log, compact, reset, or cancel operations. Each indexing call is limited to 100 documents and 1 MiB.

The dedicated tool uses an ai_tool connection. Its supplied tool object exposes
execute, invoke, call, and _call compatibility methods, while the node class
also provides the node-level execute() entry point required by n8n 2.x. Node-level
execution reads each item's JSON from the direct ai_tool input connection. When an
n8n engine execution exposes only Main runtime metadata there, the node recovers the
arguments from that invocation's in-memory runExecutionData input override, with the
persisted execution as a final compatibility fallback. If no source contains arguments,
execution fails explicitly instead of returning an empty success,
and the workflow's Main context is never treated as tool input. Successful calls return
paired n8n items whose response field contains the serialized text result. Both entry
points share the same schema validation, argument mapping, and request runner. Main-context runtime metadata such
as messages, messagesCount, and toolCallId is not treated as tool input.
Execution diagnostics contain only the selected operation, outcome, and duration; queries,
index UIDs, identifiers, documents, responses, headers, and credentials are not
logged by the tool itself.

For the AI Tool Search operation, the node owner can configure the same semantic-search defaults. The agent may override them per call with useSemanticSearch, embedder, and semanticRatio; agent values take precedence. Enabling semantic search replaces request.hybrid, while leaving it disabled preserves a manually supplied request.hybrid.

Development

pnpm install
pnpm --filter @catalogicus-international/n8n-nodes-meilisearch build
pnpm --filter @catalogicus-international/n8n-nodes-meilisearch test
pnpm --filter @catalogicus-international/n8n-nodes-meilisearch lint
pnpm --filter @catalogicus-international/n8n-nodes-meilisearch test:integration:docker
pnpm --filter @catalogicus-international/n8n-nodes-meilisearch pack

The Docker suite starts getmeili/meilisearch:v1.53.1 on a temporary local port. Chat, webhook, log-stream, and external AI-dependent behavior is covered with transport/unit tests and does not need external credentials.

Portable skills

The npm archive contains three focused skills under .agents/skills/:

• n8n-nodes-meilisearch-workflow-node for standard Main-to-Main workflows;
• n8n-nodes-meilisearch-ai-tool-node for n8n AI Agent and GigaChat AI tools;
• n8n-nodes-meilisearch-node-development for package maintenance and releases.

Copy the relevant directories into a project's .agents/skills/ when Codex should
understand these contracts. Installation does not modify the consuming project's
.agents directory automatically.

License and attribution

MIT. See LICENSE and NOTICE.