Website | Documentation | Discord

Meilisearch AI SDK

Meilisearch is a search engine for user-facing search and AI retrieval. This library provides search tools to integrate with the Vercel AI SDK.

Table of Contents

• Installation
• Quick Start
• Setup
• Example
• Using Meilisearch MCP
• API Reference
• Contributing
• License

Installation

npm install @meilisearch/ai-sdk

Quick Start

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { meilisearchSearch } from "@meilisearch/ai-sdk";

const { text } = await generateText({
  model: openai("gpt-5.4-mini"),
  system:
    "You are a movie assistant. Recommend films and where to stream them using the search tool.",
  tools: {
    search: meilisearchSearch({
      host: "MEILISEARCH_HOST",
      apiKey: "YOUR_SEARCH_API_KEY",
      indexUid: "movies",
      description: "Search movies by title or synopsis",
    }),
  },
});

console.log(text);

Setup

1. Create a project on Meilisearch Cloud or self-host
2. Create a movies index and add documents
3. Add your host and API key to .env:

MEILISEARCH_HOST=https://your-project.meilisearch.io
MEILISEARCH_API_KEY=your-search-api-key

Example

Hybrid search with filters, sorting:

const { text } = await generateText({
  model: openai("gpt-5.4-mini"),
  system: "You are a movie assistant. Recommend films using the search tool.",
  prompt: "Recommend recent action movies about revenge",
  tools: {
    search: meilisearchSearch({
      host: "MEILISEARCH_HOST",
      apiKey: "YOUR_SEARCH_API_KEY",
      indexUid: "movies",
      description: "Search movies by title or synopsis",
      searchParams: {
        limit: 10,
        sort: ["release_date:desc"],
        hybrid: {
          embedder: "default",
          semanticRatio: 0.5,
        },
      },
    }),
  },
});

console.log(text);

Using Meilisearch MCP

You can also connect your agent to the Meilisearch MCP server. The AI SDK can wrap tools from MCP servers and expose them like any other tool.

npm install @ai-sdk/mcp

import { createMCPClient } from "@ai-sdk/mcp";
import { generateText, isStepCount } from "ai";
import { openai } from "@ai-sdk/openai";

const mcpClient = await createMCPClient({
  transport: {
    type: "http",
    url: "https://your-project.meilisearch.io/mcp",
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  },
});

try {
  const tools = await mcpClient.tools();

  const { text } = await generateText({
    model: openai("gpt-5.4-mini"),
    tools,
    // Allow several steps: list indexes, describe, search, then answer
    stopWhen: isStepCount(5),
    prompt: "Recommend recent action movies about revenge",
  });

  console.log(text);
} finally {
  await mcpClient.close();
}

For the list of available tools, limitations, and troubleshooting, see the Meilisearch MCP documentation.

API Reference

Search tool

meilisearchSearch({
  // Connect with host + API key
  host: "MEILISEARCH_HOST",
  apiKey: "YOUR_SEARCH_API_KEY",
  // or reuse an existing Meilisearch client instance
  // client,

  description: "Search movies by title or synopsis",

  // Search target
  indexUid: "movies",

  // Optional SearchParams (except q, provided at runtime by the tool call)
  searchParams: {
    limit: 10,
    filter: "genres = Action",
    sort: ["release_date:desc"],
  },
});

For more details, see the Search API reference.

Multi-search tool

meilisearchMultiSearch({
  // Connect with host + API key
  host: "MEILISEARCH_HOST",
  apiKey: "YOUR_SEARCH_API_KEY",
  // or reuse an existing Meilisearch client instance
  // client,

  description: "Search movies and actors",

  // Required per-index queries (q is injected at runtime)
  queries: [
    { indexUid: "movies", limit: 5 },
    { indexUid: "actors", limit: 3 },
  ],

  // Optional federation config
  federation: {
    limit: 10,
  },
});

For more details, see the Multi-search API reference.

Search similar tool

meilisearchSearchSimilar({
  // Connect with host + API key
  host: "MEILISEARCH_HOST",
  apiKey: "YOUR_SEARCH_API_KEY",
  // or reuse an existing Meilisearch client instance
  // client,

  description: "Find similar movies by document ID",

  // Search target
  indexUid: "movies",

  // Optional similar-documents params (except id, provided at runtime)
  searchSimilarParams: {
    embedder: "default",
    limit: 5,
  },
});

For more details, see the Similar documents API reference.

Contributing

See CONTRIBUTING.md for details.

License

MIT