meilisearch-mcp

Transforms unstructured natural language requests from LLMs into structured Meilisearch API operations through the Model Context Protocol. The MeilisearchMCPServer class implements a three-layer architecture (MCP protocol layer → business logic layer → Meilisearch API layer) with standardized request processing that validates JSON schemas, delegates to specialized managers, and returns formatted responses. This enables Claude and other MCP-compatible clients to interact with Meilisearch instances conversationally without requiring direct API knowledge.

Exposes 22 Meilisearch operations as MCP tools with JSON schema validation, organized into 8 functional categories (search, index management, document handling, task monitoring, settings, keys, and system monitoring). Each tool follows a consistent pattern: schema definition → parameter validation → manager delegation → structured response formatting. The server maintains a tool registry that MCP clients can discover and invoke with type-safe parameters, enabling LLMs to understand available operations and their constraints before execution.

Implements a layered manager pattern where the MeilisearchMCPServer delegates operations to specialized managers (IndexManager, DocumentManager, TaskManager, SettingsManager, KeyManager, MonitoringManager), each responsible for a specific domain of Meilisearch functionality. This architecture cleanly separates protocol handling (MCP layer) from business logic (manager layer) from API integration (Meilisearch client layer). Each manager encapsulates domain-specific operations, error handling, and response formatting, enabling code reuse and maintainability.

Includes a testing framework with unit tests for individual managers and integration tests for end-to-end MCP protocol flows. Tests cover tool invocation, parameter validation, error handling, and response formatting. The project uses pytest for test execution and includes fixtures for Meilisearch instance setup and teardown. Enables developers to verify changes without manual testing and ensures reliability of manager implementations.

Supports multiple deployment methods for different use cases: pip install for local development, uvx for Claude Desktop integration, Docker for containerized production, and source installation with virtual environments. Each deployment method uses environment variables for configuration (MEILISEARCH_URL, MEILISEARCH_API_KEY, etc.), enabling flexible deployment across different environments. Docker integration includes pre-built images and environment variable support for container orchestration.

Provides a MeilisearchClient abstraction layer that wraps the official Meilisearch Python SDK and handles connection management, authentication, and error handling. The client is instantiated once and reused across all managers, enabling connection pooling and reducing overhead. Abstracts Meilisearch API details from managers, enabling managers to focus on domain logic without API-specific code.

Enables LLMs to execute full-text searches, faceted searches, and advanced query operations against Meilisearch indexes through natural language requests. The search capability translates natural language into Meilisearch query parameters (q, filter, facets, sort, pagination) and returns ranked results with facet aggregations. Supports complex queries including filtering by attributes, sorting by relevance or custom fields, and faceted navigation — all parameterized through the MCP protocol without requiring users to understand Meilisearch query syntax.

Manages the complete lifecycle of Meilisearch indexes through MCP tools: creating new indexes with custom settings, updating index configurations (searchable attributes, filterable attributes, sortable attributes, ranking rules), deleting indexes, and listing all indexes. The IndexManager encapsulates index operations and validates configuration parameters before applying them to Meilisearch. Enables LLMs to autonomously manage index schemas and settings without direct Meilisearch console access.

Handles document indexing operations including bulk document addition, updates, and upserts through the DocumentManager. Supports batch document operations where the server accepts document arrays, validates them against the index schema, and submits them to Meilisearch. Returns task IDs for asynchronous tracking, enabling LLMs to monitor indexing progress without blocking. Supports both JSON document arrays and CSV/NDJSON formats through Meilisearch's native import capabilities.

Monitors the status of long-running Meilisearch operations (indexing, index updates, deletions) through the TaskManager. Provides tools to retrieve task status by ID, list all tasks with filtering by status (enqueued, processing, succeeded, failed), and retrieve detailed error information for failed tasks. Enables LLMs to track operation progress without blocking, supporting multi-step workflows where subsequent operations depend on task completion.

Manages advanced Meilisearch index settings through the SettingsManager, including ranking rules (custom relevance ranking), synonyms (query expansion), stop words (ignored terms), typo tolerance (fuzzy matching), and other index-level configurations. Enables LLMs to autonomously tune search behavior without direct Meilisearch console access. Settings are applied at the index level and affect all subsequent searches on that index.

Manages Meilisearch API keys through the KeyManager, including creating new keys with scoped permissions (search-only, index-specific, action-specific), listing existing keys, updating key permissions, and deleting keys. Enables LLM agents to autonomously provision API keys for different use cases without exposing the master key. Keys can be scoped to specific indexes and actions (search, documents, settings, etc.), enabling fine-grained access control.

Provides system-level monitoring and health checks through the MonitoringManager, including retrieving Meilisearch instance statistics (database size, last update time, index count), checking instance health, and retrieving version information. Enables LLM agents to monitor Meilisearch instance status and diagnose issues without direct console access. Statistics are retrieved in real-time from the Meilisearch instance.

Implements a fully-functional MCP server that integrates with Claude Desktop and other MCP-compatible clients through the Model Context Protocol. The server handles MCP protocol communication (tool discovery, tool invocation, resource management), manages client connections, and provides standardized error handling and response formatting. Supports multiple deployment methods: pip install, uvx (Claude Desktop), Docker, and source installation with virtual environments.