Integrates with dotenv for environment variable management, specifically for Meilisearch connection configuration including host, API key, and timeout settings.
Uses Express for the web server component that hosts the MCP server implementation, enabling the StreamableHTTP transport for communication between clients and the Meilisearch API.
Employs Lerna for workspace management across the MCP server components that provide Meilisearch integration.
Provides a bridge between AI models and Meilisearch, exposing comprehensive search capabilities including document operations, advanced search features, index management, vector search, and configuration management through the Meilisearch API.
Implements the MCP server in Node.js, requiring v20 or higher for running the bridge between AI models and Meilisearch.
Uses TypeScript for type-safe implementation of the MCP server that connects AI models to Meilisearch's search engine capabilities.
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 OpenAI, HuggingFace, OpenRouter, and Ollama 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:
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" | "ollama") (Default: "openai")aiProviderApiKey
: AI provider API key for AI inferencellmModel
: 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 | List of supported models |
OpenRouter | List of supported models |
HuggingFace | List of supported models |
Ollama | List of supported models |
Example server setup
Using the MCPClient
The package exports the MCPClient class for client-side integration:
Client Methods
callTool(name, args)
Calls a specific tool on the MCP server with optional arguments.
Parameters:
name
: String - The name of the tool to callargs
: Object (Optional) - Arguments to pass to the tool
processSummary(query)
Processes data using AI to generate a human-readable summary.
Parameters:
query
: Any - The data to be summarized
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 processedoptions
: Object (Optional) - Configuration optionsspecificTools
: String[] (Optional) - Restricts tool selection to this list of tool namesjustReasoning
: Boolean (Optional) - When set totrue
, returns only the AI's reasoning without executing the selected toolprovideSummary
: Boolean (Optional) - When set totrue
, generates a concise summary of the search results along with the regular response
Starting the Server
You can start the server programmatically:
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
- System Tools: Health checks, version info, server stats.
- Index Tools: Manage indexes (create, update, delete, list).
- Document Tools: Add, update, delete, and retrieve documents.
- Search Tools: Advanced search, including vector search.
- Settings Tools: Configure index settings.
- Task Tools: Manage asynchronous tasks.
- 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 thesearch
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).
Related MCP Servers
- GoMIT License
- JavaScript
- PythonMIT License
- PythonMIT License