Meilisearch MCP Communication Hub

Core Engine | Cloud Offering | Official Reference | Community Chat (Discord)

⚡ Bridge your Large Language Models to Meilisearch for instantaneous, AI-driven data retrieval and orchestration! 🔍

❓ What is This Component?

This tool serves as a standardized Model Context Protocol (MCP) gateway, facilitating communication between any MCP-compliant LLM interface (like Anthropic's Claude or custom agent frameworks) and your Meilisearch instance(s). Operating via stdio, it translates conversational instructions into precise Meilisearch API calls, effectively removing the need for developers to master the underlying REST API.

Key Advantages: - 🤖 Protocol Agnostic: Compatible with any MCP client structure. - 🗣️ Conversational Interface: Manage complex data operations through natural language prompts. - 🚀 Abstraction Layer: Completely bypass the requirement to learn Meilisearch's specific HTTP endpoints. - 🔧 Complete Feature Parity: Exposes the full spectrum of Meilisearch functionalities. - 🔄 Multi-Instance Handling: Ability to maintain and switch between disparate Meilisearch servers dynamically. - 📡 Transport Layer: Currently leverages standard input/output streams (stdio); native support is evolving.

✨ Core Capabilities Overview

• 📊 Schema & Data Control: Provisioning, modification, and removal of search indexes and their associated documents.
• 🔍 Advanced Querying: Executing complex searches across single or aggregated sets of indices, including filtering and sorting.
• ⚙️ System Tuning: Direct access to fine-tune ranking algorithms and search parameters.
• 📈 Asynchronous Operation Tracking: Monitoring the status and progression of backend tasks (like indexing).
• 🔐 Credential Management: Generating, inspecting, and revoking access keys.
• 🏥 Operational Health: Performing status checks on the search engine's availability and performance.
• 🐍 Implementation Detail: Written in Python (A companion TypeScript implementation also exists: TypeScript Version Link)

🚀 Initial Setup Guide

Implement this adapter in three quick phases:

1️⃣ Installation of the Package

Use your preferred Python environment manager:

bash

Standard installation via pip

pip install meilisearch-mcp

Recommended installation using uv (faster dependency resolution)

uvx -n meilisearch-mcp

2️⃣ Client Configuration (Example: Claude Desktop)

Integrate the server executable path into your client's configuration file (claude_desktop_config.json):

{ "mcpServers": { "meilisearch": { "command": "uvx", "args": ["-n", "meilisearch-mcp"] } } }

3️⃣ Start Meilisearch Engine

Ensure your target Meilisearch instance is operational:

bash

Via Docker (Highly Recommended)

docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

Via Homebrew (macOS)

brew install meilisearch meilisearch

Once complete, your AI entity is ready to converse with and manage your search infrastructure! 🎉

📚 Interaction Scenarios

💬 Natural Language Prompts to the AI:

You: "Establish a fresh collection named 'products' designating 'id' as the sole primary identifier." AI: Initiating index creation... ✓ Index 'products' successfully provisioned!

You: "Ingest a batch of product records into that collection." AI: Processing document upload... ✓ Successfully incorporated 5 new records into 'products'.

You: "Execute a search query targeting items priced below 50 currency units containing the term 'electronics'." AI: Analyzing query against indices... Found 12 matching documents!

🔍 Complex Cross-Index Query Example:

You: "Execute a broad search for 'machine learning' across every index I possess, ensuring results are ordered chronologically by creation date." AI: Scanning all data sources... Aggregate result count: 47 from 3 distinct collections: - 'blog_posts': 23 relevant articles concerning ML - 'documentation': 15 technical guides - 'tutorials': 9 practical walkthroughs

🛠️ Tool Capabilities Detail

🔗 Connection Handling

- `get-connection-settings`: Report current engine URL and key status. - `update-connection-settings`: Modify endpoint URL or API credential dynamically.

📁 Index Structure Management

- `create-index`: Deploy a new index, optionally specifying its primary key. - `list-indexes`: Return an inventory of all active indices. - `delete-index`: Erase an index and purge all associated data. - `get-index-metrics`: Retrieve granular performance statistics for a specific index.

📄 Document Lifecycle

- `get-documents`: Fetch records from an index, supporting offset/limit for pagination. - `add-documents`: Upsert (add or replace) document batches.

🔍 Search Operations

- `search`: Flexible querying supporting query parameters, complex filtering, sort directives, and faceting. - `multi-index-search`: Query against several indices simultaneously. - `vector-search`: Execute searches using embedding vectors (for semantic matching). - `hybrid-search`: Combine textual relevance with vector similarity.

⚙️ Configuration Layer

- `get-settings`: Retrieve the current configuration blueprint of an index. - `update-settings`: Adjust parameters like relevance rules, attribute definitions, and tolerance settings.

🔐 Security Framework

- `get-keys`: Enumerate existing API credentials. - `create-key`: Generate new keys with scoped permissions. - `delete-key`: Revoke a specific credential.

📊 System Diagnostics

- `health-check`: Quick availability verification. - `get-task`/`get-tasks`: Query the asynchronous task queue status. - `get-version`: Fetch the running Meilisearch binary version.

🌍 Runtime Environment Customization

Default connection parameters can be overridden via environment variables:

bash MEILI_HTTP_ADDR=http://remote-server:7700 # Override default host/port MEILI_MASTER_KEY=secret_key_for_default # Provide a default credential

💻 Development & Contribution Guide

Setup for Local Iteration

1. Initialize Meilisearch: Start the engine instance locally (Docker recommended). bash docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

2. Install Dependencies: Utilize uv for environment creation and dependency installation. bash pip install uv uv venv source .venv/bin/activate # Linux/macOS uv pip install -e .[dev]

3. Execution & Quality Checks: bash # Run full test suite python -m pytest tests/ -v

# Enforce code formatting standards black src/ tests/

Testing with the MCP Inspector

To interactively debug the tool's connection to an LLM client framework:

bash npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 Community Engagement

We strongly encourage feedback and contributions:

• 💬 Support/Discussion: Join our Discord Channel
• 🐛 Reporting Bugs: Open an Issue on GitHub
• 💡 Suggesting Enhancements: Submit feature requests via the Issues tracker.

📦 Release and Publishing Workflow

This project automates deployment to PyPI based on changes merged into the main branch. Automated CI/CD handles packaging and publishing upon version bumps in pyproject.toml.

To initiate a new official release (e.g., from v0.4.0 to v0.5.0):

1. Create a release branch (git checkout -b release/v0.5.0).
2. Increment the version in pyproject.toml.
3. Commit and merge the resulting PR into main.
4. GitHub Actions take over, building and publishing the package to PyPI.

Available MCP Tools Listing

Engine Connectivity

• get-connection-settings: Obtain current engine address and credential status.
• update-connection-settings: Modify the active connection target.

Index & Data Operations

• create-index: Initialize a new data collection.
• list-indexes: Retrieve the full index catalog.
• delete-index: Permanently remove a collection.
• add-documents: Upload or replace data records.
• get-documents: Extract records with pagination control.

Search Functionality

• search: Perform primary text searches with query parameters.

System Configuration & Oversight

• update-settings: Modify relevance scoring parameters.
• get-settings: Inspect current index configuration.
• health-check: Verify server responsiveness.
• get-task/get-tasks: Query job queue status.
• create-key: Provision new access credentials.

---

Meilisearch is engineered for exceptional search performance and user experience.
Explore the core technology at meilisearch.com