Meilisearch MCP Server

Instructions

Implementation Reference

• src/tools/vector-tools.ts:141-189 (handler)

  The async handler function that performs the vector search by parsing inputs, validating requirements (vector or embedder+query), building search parameters, and POSTing to Meilisearch's /indexes/{indexUid}/search endpoint.
  async ({ indexUid, vector, limit, offset, filter, embedder, attributes, query, hybrid, hybridRatio }) => { try { const searchParams: Record<string, any> = {}; // Add required vector parameter if (vector) { try { searchParams.vector = JSON.parse(vector); } catch (parseError) { return { isError: true, content: [{ type: "text", text: "Vector must be a valid JSON array" }], }; } } // Add embedder parameters if (embedder) { searchParams.embedder = embedder; if (query !== undefined) { searchParams.q = query; } } // Ensure we have either vector or (embedder + query) if (!vector && (!embedder || query === undefined)) { return { isError: true, content: [{ type: "text", text: "Either 'vector' or both 'embedder' and 'query' must be provided" }], }; } // Add optional parameters if (limit !== undefined) searchParams.limit = limit; if (offset !== undefined) searchParams.offset = offset; if (filter) searchParams.filter = filter; if (attributes?.length) searchParams.attributes = attributes; if (hybrid !== undefined) searchParams.hybrid = hybrid; if (hybridRatio !== undefined) searchParams.hybridRatio = hybridRatio; const response = await apiClient.post(`/indexes/${indexUid}/search`, searchParams); return { content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }], }; } catch (error) { return createErrorResponse(error); } }
• src/tools/vector-tools.ts:129-140 (schema)

  Zod schema defining the input parameters for the vector-search tool.
  { indexUid: z.string().describe("Unique identifier of the index"), vector: z.string().describe("JSON array representing the vector to search for"), limit: z.number().min(1).max(1000).optional().describe("Maximum number of results to return (default: 20)"), offset: z.number().min(0).optional().describe("Number of results to skip (default: 0)"), filter: z.string().optional().describe("Filter to apply (e.g., 'genre = horror AND year > 2020')"), embedder: z.string().optional().describe("Name of the embedder to use (if omitted, a 'vector' must be provided)"), attributes: z.array(z.string()).optional().describe("Attributes to include in the vector search"), query: z.string().optional().describe("Text query to search for (if using 'embedder' instead of 'vector')"), hybrid: z.boolean().optional().describe("Whether to perform a hybrid search (combining vector and text search)"), hybridRatio: z.number().min(0).max(1).optional().describe("Ratio of vector vs text search in hybrid search (0-1, default: 0.5)"), },
• src/tools/vector-tools.ts:126-190 (registration)

  Direct registration of the 'vector-search' tool on the MCP server using server.tool(), including description, input schema, and handler.
  server.tool( "vector-search", "Perform a vector search in a Meilisearch index", { indexUid: z.string().describe("Unique identifier of the index"), vector: z.string().describe("JSON array representing the vector to search for"), limit: z.number().min(1).max(1000).optional().describe("Maximum number of results to return (default: 20)"), offset: z.number().min(0).optional().describe("Number of results to skip (default: 0)"), filter: z.string().optional().describe("Filter to apply (e.g., 'genre = horror AND year > 2020')"), embedder: z.string().optional().describe("Name of the embedder to use (if omitted, a 'vector' must be provided)"), attributes: z.array(z.string()).optional().describe("Attributes to include in the vector search"), query: z.string().optional().describe("Text query to search for (if using 'embedder' instead of 'vector')"), hybrid: z.boolean().optional().describe("Whether to perform a hybrid search (combining vector and text search)"), hybridRatio: z.number().min(0).max(1).optional().describe("Ratio of vector vs text search in hybrid search (0-1, default: 0.5)"), }, async ({ indexUid, vector, limit, offset, filter, embedder, attributes, query, hybrid, hybridRatio }) => { try { const searchParams: Record<string, any> = {}; // Add required vector parameter if (vector) { try { searchParams.vector = JSON.parse(vector); } catch (parseError) { return { isError: true, content: [{ type: "text", text: "Vector must be a valid JSON array" }], }; } } // Add embedder parameters if (embedder) { searchParams.embedder = embedder; if (query !== undefined) { searchParams.q = query; } } // Ensure we have either vector or (embedder + query) if (!vector && (!embedder || query === undefined)) { return { isError: true, content: [{ type: "text", text: "Either 'vector' or both 'embedder' and 'query' must be provided" }], }; } // Add optional parameters if (limit !== undefined) searchParams.limit = limit; if (offset !== undefined) searchParams.offset = offset; if (filter) searchParams.filter = filter; if (attributes?.length) searchParams.attributes = attributes; if (hybrid !== undefined) searchParams.hybrid = hybrid; if (hybridRatio !== undefined) searchParams.hybridRatio = hybridRatio; const response = await apiClient.post(`/indexes/${indexUid}/search`, searchParams); return { content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }], }; } catch (error) { return createErrorResponse(error); } } );
• src/index.ts:68-68 (registration)

  Registers the vector tools module (including vector-search) on the main MCP server instance.
  registerVectorTools(server);