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);