mcp-meilisearch

MCP Meilisearch API Server

A Model Context Protocol (MCP) server implementation that provides a bridge between AI models and the Meilisearch search engine.

Overview

• MCP Server: Exposes Meilisearch APIs as tools using the Model Context Protocol.
• Web Client Demo: A demo interface showcasing search functionalities.
• AI Inference: Intelligent tool selection based on user queries.

Key Features

• Multiple Transport Options: Supports both STDIO and StreamableHTTP transports.
• Meilisearch API Support: Full access to Meilisearch functionalities.
• Web Client Demo: Updated interface showcasing search capabilities and features.
• AI Inference: Leverages LLMs from providers such as OpenAIo HuggingFace to intelligently determine and utilize the most suitable tool for user queries.

Getting Started

Prerequisites

• Node.js v20 or higher.
• A running Meilisearch instance (local or remote).
• API key for Meilisearch (if required).
• AI provider API key (if using AI inference).

Installation

Install the package:

# Using npm
npm install mcp-meilisearch

# Using yarn
yarn add mcp-meilisearch

# Using pnpm
pnpm add mcp-meilisearch

Options

Meilisearch Connection Options

• meilisearchHost: URL of the Meilisearch instance (Default: "http://localhost:7700")
• meilisearchApiKey: API key for authenticating with Meilisearch (Default: "")

MCP Server Options

• transport: Transport type for MCP server ("http" | "stdio") (Default: "http")
• httpPort: HTTP port for MCP server (Default: 4995)
• mcpEndpoint: MCP endpoint path (Default: "/mcp")

Session Options

• sessionTimeout: Session timeout in milliseconds (Default: 3600000)
• sessionCleanupInterval: Session cleanup interval in milliseconds (Default: 60000)

AI Inference Options

• aiProviderName: Name of the AI provider ("openai" | "huggingface" | "openrouter") (Default: "openai")
• aiProviderApiKey: AI provider API key for AI inference
• llmModel: AI model to use (Default: "gpt-3.5-turbo")

Please be aware that not all models support function calling, which is required for proper AI inference in this package. Make sure to select a model that supports the tools parameter.

Provider	Supported Models
OpenAI	GPT-4, GPT-3.5-turbo and other compatible models
OpenRouter	Models with tools parameter support
HuggingFace	Models with function calling capability

Example server setup

await mcpMeilisearchServer({
  meilisearchHost: "http://localhost:7700",
  aiProviderName: "openrouter",
  aiProviderApiKey: "your_openrouter_api_key",
  llmModel: "anthropic/claude-3-opus", // Make sure to use a model that supports function calling
});

Using the MCPClient

The package exports the MCPClient class for client-side integration:

import { MCPClient } from "mcp-meilisearch/client";

const client = new MCPClient("mcp-meilisearch-client");

await client.connectToServer("http://localhost:4995/mcp");

const result = await client.callTool("global-search", {
  q: "search kiosco antonio",
});

// Use AI inference to choose the most appropriate tool

const result = await client.callToolWithAI("Find articles about cucumber");
console.log(`Tool used: ${result.toolUsed}`);
console.log(`Reasoning: ${result.reasoning}`);
console.log(`Results: ${JSON.stringify(result.data)}`);

AI Inference Client Methods

callToolWithAI(query, options)

Processes a user query through AI to determine and execute the most appropriate tool.

Parameters:

• query: String - The user's query or request to be processed
• options: Object (Optional) - Configuration options
  • specificTools: String[] (Optional) - Restricts tool selection to this list of tool names
  • justReasoning: Boolean (Optional) - When set to true, returns only the AI's reasoning without executing the selected tool

Starting the Server

You can start the server programmatically:

import mcpMeilisearchServer from "mcp-meilisearch";

await mcpMeilisearchServer({
  meilisearchHost: "http://localhost:7700",
  meilisearchApiKey: "your_meilisearch_api_key",
  aiProviderName: "openai",
  aiProviderApiKey: "your_ai_provider_api_key", // Required for AI inference
  llmModel: "gpt-4",
});

Tools

The MCP server exposes various tools that allow you to interact with Meilisearch functionalities. Each tool corresponds to a specific Meilisearch API endpoint, enabling you to perform operations such as searching, indexing, and managing documents.

Tool Categories

1. System Tools: Health checks, version info, server stats.
2. Index Tools: Manage indexes (create, update, delete, list).
3. Document Tools: Add, update, delete, and retrieve documents.
4. Search Tools: Advanced search, including vector search.
5. Settings Tools: Configure index settings.
6. Task Tools: Manage asynchronous tasks.
7. Vector Tools: Experimental vector search capabilities.

System Tools

health

• Description: Check if the Meilisearch server is healthy.

version

• Description: Get the version information of the Meilisearch server.

info

• Description: Get the system information of the Meilisearch server.

stats

• Description: Get statistics about all indexes or a specific index.
• Parameters:
  • indexUid (string, optional): Unique identifier of the index.

get-tasks

• Description: Get information about tasks with optional filtering.
• Parameters:
  • limit (number, optional): Maximum number of tasks to return.
  • from (number, optional): Task uid from which to start fetching.
  • status (string, optional): Status of tasks to return.
  • type (string, optional): Type of tasks to return.
  • indexUids (string[], optional): UIDs of the indexes on which tasks were performed.

delete-tasks

• Description: Delete tasks based on provided filters.
• Parameters:
  • statuses (string[], optional): Statuses of tasks to delete.
  • types (string[], optional): Types of tasks to delete.
  • indexUids (string[], optional): UIDs of the indexes on which tasks to delete were performed.
  • uids (number[], optional): UIDs of the tasks to delete.
  • canceledBy (number[], optional): UIDs of the tasks that canceled tasks to delete.
  • beforeUid (number, optional): Delete tasks whose uid is before this value.
  • beforeStartedAt (string, optional): Delete tasks that started processing before this date (ISO 8601 format).
  • beforeFinishedAt (string, optional): Delete tasks that finished processing before this date (ISO 8601 format).

Index Tools

list-indexes

• Description: List all indexes in the Meilisearch instance.
• Parameters:
  • limit (number, optional): Maximum number of indexes to return.
  • offset (number, optional): Number of indexes to skip.

get-index

• Description: Get information about a specific Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.

create-index

• Description: Create a new Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier for the new index.
  • primaryKey (string, optional): Primary key for the index.

update-index

• Description: Update a Meilisearch index (currently only supports updating the primary key).
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • primaryKey (string, required): New primary key for the index.

delete-index

• Description: Delete a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index to delete.

swap-indexes

• Description: Swap two or more indexes in Meilisearch.
• Parameters:
  • indexes (string, required): JSON array of index pairs to swap, e.g. [["movies", "movies_new"]].

Document Tools

get-documents

• Description: Get documents from a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • limit (number, optional): Maximum number of documents to return (default: 20).
  • offset (number, optional): Number of documents to skip (default: 0).
  • fields (string[], optional): Fields to return in the documents.
  • filter (string, optional): Filter query to apply.

get-document

• Description: Get a document by its ID from a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • documentId (string, required): ID of the document to retrieve.
  • fields (string[], optional): Fields to return in the document.

add-documents

• Description: Add documents to a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • documents (string, required): JSON array of documents to add.
  • primaryKey (string, optional): Primary key for the documents.

update-documents

• Description: Update documents in a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • documents (string, required): JSON array of documents to update.
  • primaryKey (string, optional): Primary key for the documents.

delete-document

• Description: Delete a document by its ID from a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • documentId (string, required): ID of the document to delete.

delete-documents

• Description: Delete multiple documents by their IDs from a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • documentIds (string, required): JSON array of document IDs to delete.

delete-all-documents

• Description: Delete all documents in a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.

Search Tools

search

• Description: Search for documents in a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • q (string, required): Search query.
  • limit (number, optional): Maximum number of results to return (default: 20).
  • offset (number, optional): Number of results to skip (default: 0).
  • filter (string, optional): Filter query to apply.
  • sort (string[], optional): Attributes to sort by, e.g. ["price:asc"].
  • facets (string[], optional): Facets to return.
  • attributesToRetrieve (string[], optional): Attributes to include in results.
  • attributesToCrop (string[], optional): Attributes to crop.
  • cropLength (number, optional): Length at which to crop cropped attributes.
  • attributesToHighlight (string[], optional): Attributes to highlight.
  • highlightPreTag (string, optional): Tag to insert before highlighted text.
  • highlightPostTag (string, optional): Tag to insert after highlighted text.
  • showMatchesPosition (boolean, optional): Whether to include match positions in results.
  • matchingStrategy (string, optional): Matching strategy: 'all' or 'last'.

multi-search

• Description: Perform multiple searches in one request.
• Parameters:
  • queries (string, required): JSON array of search queries, each containing the same parameters as the search tool.

global-search

• Description: Search for a term across all available Meilisearch indexes and return combined results.
• Parameters:
  • q (string, required): Search query.
  • limit (number, optional): Maximum number of results to return per index (default: 20).
  • attributesToRetrieve (string[], optional): Attributes to include in results.

facet-search

• Description: Search for facet values matching specific criteria.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • facetName (string, required): Name of the facet to search.
  • facetQuery (string, optional): Query to match against facet values.
  • filter (string, optional): Filter to apply to the base search.

Settings Tools

get-settings

• Description: Get all settings for a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.

update-settings

• Description: Update settings for a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • settings (string, required): JSON object containing settings to update.

reset-settings

• Description: Reset all settings for a Meilisearch index to their default values.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.

Get Settings Tools

The following tools retrieve specific settings for a Meilisearch index:

• get-displayed-attributes
• get-searchable-attributes
• get-filterable-attributes
• get-sortable-attributes
• get-ranking-rules
• get-stop-words
• get-synonyms
• get-typo-tolerance
• get-pagination
• get-faceting
• get-dictionary
• get-proximity-precision
• get-separator-tokens
• get-non-separator-tokens
• get-word-dictionary

All these tools have the same parameter:

• indexUid (string, required): Unique identifier of the index.

Update Settings Tools

The following tools update specific settings for a Meilisearch index:

• update-displayed-attributes

  • indexUid (string, required): Unique identifier of the index.
  • displayedAttributes (string, required): JSON array of attributes to display, e.g. ["title", "description"].

• update-searchable-attributes

  • indexUid (string, required): Unique identifier of the index.
  • searchableAttributes (string, required): JSON array of attributes that can be searched, e.g. ["title", "description"].

• update-filterable-attributes

  • indexUid (string, required): Unique identifier of the index.
  • filterableAttributes (string, required): JSON array of attributes that can be used as filters, e.g. ["genre", "director"].

• update-sortable-attributes

  • indexUid (string, required): Unique identifier of the index.
  • sortableAttributes (string, required): JSON array of attributes that can be used for sorting, e.g. ["price", "date"].

• update-ranking-rules

  • indexUid (string, required): Unique identifier of the index.
  • rankingRules (string, required): JSON array of ranking rules, e.g. ["typo", "words", "proximity", "attribute", "sort", "exactness"].

• update-stop-words

  • indexUid (string, required): Unique identifier of the index.
  • stopWords (string, required): JSON array of words to ignore in search queries, e.g. ["the", "a", "an"].

• update-synonyms

  • indexUid (string, required): Unique identifier of the index.
  • synonyms (string, required): JSON object mapping words to their synonyms, e.g. {"movie": ["film"]}.

• update-typo-tolerance

  • indexUid (string, required): Unique identifier of the index.
  • typoTolerance (string, required): JSON object with typo tolerance configuration, e.g. {"enabled": true, "minWordSizeForTypos": {"oneTypo": 5, "twoTypos": 9}}.

• update-pagination

  • indexUid (string, required): Unique identifier of the index.
  • pagination (string, required): JSON object with pagination configuration, e.g. {"maxTotalHits": 1000}.

• update-faceting

  • indexUid (string, required): Unique identifier of the index.
  • faceting (string, required): JSON object with faceting configuration, e.g. {"maxValuesPerFacet": 100}.

• update-dictionary

  • indexUid (string, required): Unique identifier of the index.
  • dictionary (string, required): JSON array of words to consider as a single word, e.g. ["San Francisco", "New York"].

• update-proximity-precision

  • indexUid (string, required): Unique identifier of the index.
  • proximityPrecision (string, required): String with proximity precision value, can be 'byWord' or 'byAttribute'.

• update-separator-tokens

  • indexUid (string, required): Unique identifier of the index.
  • separatorTokens (string, required): JSON array of tokens that should be considered as word separators, e.g. ["-", "_"].

• update-non-separator-tokens

  • indexUid (string, required): Unique identifier of the index.
  • nonSeparatorTokens (string, required): JSON array of tokens that should not be considered as word separators, e.g. ["@", "."].

• update-word-dictionary

  • indexUid (string, required): Unique identifier of the index.
  • wordDictionary (string, required): JSON array of custom words to add to the dictionary, e.g. ["cbuilder", "meilisearch"].

Reset Settings Tools

The following tools reset specific settings for a Meilisearch index to their default values:

• reset-displayed-attributes
• reset-searchable-attributes
• reset-filterable-attributes
• reset-sortable-attributes
• reset-ranking-rules
• reset-stop-words
• reset-synonyms
• reset-typo-tolerance
• reset-pagination
• reset-faceting
• reset-dictionary
• reset-proximity-precision
• reset-separator-tokens
• reset-non-separator-tokens
• reset-word-dictionary

All these reset tools have the same parameter:

• indexUid (string, required): Unique identifier of the index.

Task Tools

list-tasks

• Description: List tasks with optional filtering.
• Parameters:
  • limit (number, optional): Maximum number of tasks to return.
  • from (number, optional): Task uid from which to start fetching.
  • statuses (string[], optional): Statuses of tasks to return.
  • types (string[], optional): Types of tasks to return.
  • indexUids (string[], optional): UIDs of the indexes on which tasks were performed.
  • uids (number[], optional): UIDs of specific tasks to return.

get-task

• Description: Get information about a specific task.
• Parameters:
  • taskUid (number, required): Unique identifier of the task.

cancel-tasks

• Description: Cancel tasks based on provided filters.
• Parameters:
  • statuses (string[], optional): Statuses of tasks to cancel.
  • types (string[], optional): Types of tasks to cancel.
  • indexUids (string[], optional): UIDs of the indexes on which tasks to cancel were performed.
  • uids (number[], optional): UIDs of the tasks to cancel.

wait-for-task

• Description: Wait for a specific task to complete.
• Parameters:
  • taskUid (number, required): Unique identifier of the task to wait for.
  • timeoutMs (number, optional): Maximum time to wait in milliseconds (default: 5000).
  • intervalMs (number, optional): Polling interval in milliseconds (default: 500).

Vector Tools

enable-vector-search

• Description: Enable the vector search experimental feature in Meilisearch.

get-experimental-features

• Description: Get the status of experimental features in Meilisearch.

update-embedders

• Description: Configure embedders for vector search.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • embedders (string, required): JSON object containing embedder configurations.

get-embedders

• Description: Get the embedders configuration for an index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.

reset-embedders

• Description: Reset the embedders configuration for an index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.

vector-search

• Description: Perform a vector search in a Meilisearch index.
• Parameters:
  • indexUid (string, required): Unique identifier of the index.
  • vector (string, required): JSON array representing the vector to search for.
  • limit (number, optional): Maximum number of results to return (default: 20).
  • offset (number, optional): Number of results to skip (default: 0).
  • filter (string, optional): Filter to apply (e.g., 'genre = horror AND year > 2020').
  • embedder (string, optional): Name of the embedder to use (if omitted, a 'vector' must be provided).
  • attributes (string[], optional): Attributes to include in the vector search.
  • query (string, optional): Text query to search for (if using 'embedder' instead of 'vector').
  • hybrid (boolean, optional): Whether to perform a hybrid search (combining vector and text search).
  • hybridRatio (number, optional): Ratio of vector vs text search in hybrid search (0-1, default: 0.5).