Meilisearch MCP Server

What is Meilisearch MCP Server about?

Enables any MCP‑compatible client (Claude, OpenAI agents, etc.) to control a Meilisearch instance through conversational commands. The server runs as a stdio process, translating natural‑language intents into Meilisearch API calls.

How to use Meilisearch MCP Server?

Install

pip install meilisearch-mcp   # or uvx -n meilisearch-mcp (recommended)

Configure an MCP client (example for Claude Desktop):

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

Run a Meilisearch instance (Docker recommended):

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

Start the MCP server (the client will launch uvx -n meilisearch-mcp automatically).

Optional – Docker image for containerised workflows:

docker pull getmeili/meilisearch-mcp:latest
docker run -it -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
            -e MEILI_MASTER_KEY=your-master-key getmeili/meilisearch-mcp:latest

Key features of Meilisearch MCP Server

Index creation, listing, deletion, and metric retrieval
Document addition, update, pagination, and bulk import
Advanced search across single or multiple indices with filtering, sorting, faceting, and hybrid (keyword + semantic) options
Full settings management (ranking rules, typo tolerance, searchable attributes, etc.)
API‑key lifecycle handling and permission control
Health checks, system statistics, and task monitoring
Dynamic connection switching via environment variables or MCP commands
Pure Python implementation with a TypeScript counterpart available

Use cases of Meilisearch MCP Server

RAG assistants: let an LLM fetch relevant documents from a vector‑enabled Meilisearch index during a conversation.
Customer‑support bots: agents can create, update, or prune knowledge‑base indexes on‑the‑fly.
Workflow automation: embed search steps in n8n, Zapier, or custom pipelines using the Docker image.
Rapid prototyping: developers can experiment with search‑driven AI features without writing API calls.
Multi‑tenant SaaS: switch between different Meilisearch instances for different users through natural‑language commands.

FAQ from the Meilisearch MCP Server

Q: Which Python version is required? A: Python 3.9 or newer.

Q: Can I run the server without Docker? A: Yes, install the package via pip/uvx and launch it directly; Docker is only a convenience for isolated environments.

Q: How does authentication work? A: Set MEILI_MASTER_KEY (or a scoped key) as an environment variable, or update the connection settings via MCP commands.

Q: Is there support for vector (semantic) search? A: Yes, the server exposes a search tool that can include vector queries when the underlying Meilisearch instance is configured for hybrid search.

Q: What transport does the server use? A: Currently stdio; future native Meilisearch MCP support is planned.

🤔 What is this?

The Meilisearch MCP Server is a Model Context Protocol server that enables any MCP-compatible client (including Claude, OpenAI agents, and other LLMs) to interact with Meilisearch. This stdio-based server allows AI assistants to manage search indices, perform searches, and handle your data through natural conversation.

Why use this?

🤖 Universal Compatibility - Works with any MCP client, not just Claude
🗣️ Natural Language Control - Manage Meilisearch through conversation with any LLM
🚀 Zero Learning Curve - No need to learn Meilisearch's API
🔧 Full Feature Access - All Meilisearch capabilities at your fingertips
🔄 Dynamic Connections - Switch between Meilisearch instances on the fly
📡 stdio Transport - Currently uses stdio; native Meilisearch MCP support coming soon!

✨ Key Features

📊 Index & Document Management - Create, update, and manage search indices
🔍 Smart Search - Search across single or multiple indices with advanced filtering
⚙️ Settings Configuration - Fine-tune search relevancy and performance
📈 Task Monitoring - Track indexing progress and system operations
🔐 API Key Management - Secure access control
🏥 Health Monitoring - Keep tabs on your Meilisearch instance
🐍 Python Implementation - TypeScript version also available

🚀 Quick Start

Get up and running in just 3 steps!

1️⃣ Install the package

# Using pip
pip install meilisearch-mcp

# Or using uvx (recommended)
uvx -n meilisearch-mcp

2️⃣ Configure Claude Desktop

Add this to your claude_desktop_config.json:

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

3️⃣ Start Meilisearch

# Using Docker (recommended)
docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

# Or using Homebrew
brew install meilisearch
meilisearch

That's it! Now you can ask your AI assistant to search and manage your Meilisearch data! 🎉

📚 Examples

💬 Talk to your AI assistant naturally:

You: "Create a new index called 'products' with 'id' as the primary key"
AI: I'll create that index for you... ✓ Index 'products' created successfully!

You: "Add some products to the index"
AI: I'll add those products... ✓ Added 5 documents to 'products' index

You: "Search for products under $50 with 'electronics' in the category"
AI: I'll search for those products... Found 12 matching products!

🔍 Advanced Search Example:

You: "Search across all my indices for 'machine learning' and sort by date"
AI: Searching across all indices... Found 47 results from 3 indices:
- 'blog_posts': 23 articles about ML
- 'documentation': 15 technical guides  
- 'tutorials': 9 hands-on tutorials

🔧 Installation

Prerequisites

Python ≥ 3.9
Running Meilisearch instance
MCP-compatible client (Claude Desktop, OpenAI agents, etc.)

From PyPI

pip install meilisearch-mcp

From Source (for development)

# Clone repository
git clone https://github.com/meilisearch/meilisearch-mcp.git
cd meilisearch-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Using Docker

Perfect for containerized environments like n8n workflows!

From Docker Hub

# Pull the latest image
docker pull getmeili/meilisearch-mcp:latest

# Or a specific version
docker pull getmeili/meilisearch-mcp:0.5.0

# Run the container
docker run -it \
  -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  getmeili/meilisearch-mcp:latest

Build from Source

# Build your own image
docker build -t meilisearch-mcp .
docker run -it \
  -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  meilisearch-mcp

Integration with n8n

For n8n workflows, you can use the Docker image directly in your setup:

meilisearch-mcp:
  image: getmeili/meilisearch-mcp:latest
  environment:
    - MEILI_HTTP_ADDR=http://meilisearch:7700
    - MEILI_MASTER_KEY=masterKey

🛠️ What Can You Do?

View current connection settings
Switch between Meilisearch instances dynamically
Update API keys on the fly

Create new indices with custom primary keys
List all indices with stats
Delete indices and their data
Get detailed index metrics

Add or update documents
Retrieve documents with pagination
Bulk import data

Search with filters, sorting, and facets
Multi-index search
Semantic search with vectors
Hybrid search (keyword + semantic)

Configure ranking rules
Set up faceting and filtering
Manage searchable attributes
Customize typo tolerance

Create and manage API keys
Set granular permissions
Monitor key usage

Health checks
System statistics
Task monitoring
Version information

🌍 Environment Variables

Configure default connection settings:

MEILI_HTTP_ADDR=http://localhost:7700  # Default Meilisearch URL
MEILI_MASTER_KEY=your_master_key       # Optional: Default API key

💻 Development

Setting Up Development Environment

Start Meilisearch:

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

Install Development Dependencies:
```
uv pip install -r requirements-dev.txt
```
Run Tests:
```
python -m pytest tests/ -v
```
Format Code:
```
black src/ tests/
```

Testing with MCP Inspector

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 Community & Support

We'd love to hear from you! Here's how to get help and connect:

💬 Join our Discord - Chat with the community
🐛 Report Issues - Found a bug? Let us know!
💡 Feature Requests - Have an idea? We're listening!
📖 Meilisearch Docs - Learn more about Meilisearch

🤗 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Make your changes and run tests
Format your code with black
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

See our Contributing Guidelines for more details.

📦 Release Process

This project uses automated versioning and publishing. When the version in pyproject.toml changes on the main branch, the package is automatically published to PyPI.

See the Release Process section for detailed instructions.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Available Tools

Connection Management

get-connection-settings: View current Meilisearch connection URL and API key status
update-connection-settings: Update URL and/or API key to connect to a different instance

Index Management

create-index: Create a new index with optional primary key
list-indexes: List all available indexes
delete-index: Delete an existing index and all its documents
get-index-metrics: Get detailed metrics for a specific index

Document Operations

get-documents: Retrieve documents from an index with pagination
add-documents: Add or update documents in an index

Search

search: Flexible search across single or multiple indices with filtering and sorting options

Settings Management

get-settings: View current settings for an index
update-settings: Update index settings (ranking, faceting, etc.)

API Key Management

get-keys: List all API keys
create-key: Create new API key with specific permissions
delete-key: Delete an existing API key

Task Management

get-task: Get information about a specific task
get-tasks: List tasks with optional filters
cancel-tasks: Cancel pending or enqueued tasks
delete-tasks: Delete completed tasks

System Monitoring

health-check: Basic health check
get-health-status: Comprehensive health status
get-version: Get Meilisearch version information
get-stats: Get database statistics
get-system-info: Get system-level information

Development Setup

Prerequisites

Start Meilisearch server:

# Using Docker (recommended for development)
docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

# Or using brew (macOS)
brew install meilisearch
meilisearch

# Or download from https://github.com/meilisearch/meilisearch/releases

Install development tools:

# Install uv for Python package management
pip install uv

# Install Node.js for MCP Inspector testing
# Visit https://nodejs.org/ or use your package manager

Running Tests

This project includes comprehensive integration tests that verify MCP tool functionality:

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mcp_client.py -v

# Run tests with coverage report
python -m pytest --cov=src tests/

# Run tests in watch mode (requires pytest-watch)
pytest-watch tests/

Important: Tests require a running Meilisearch instance on http://localhost:7700.

Code Quality

# Format code with Black
black src/ tests/

# Run type checking (if mypy is configured)
mypy src/

# Lint code (if flake8 is configured)
flake8 src/ tests/

Contributing Guidelines

Fork and clone the repository
Set up development environment following the Development Setup section above
Create a feature branch from main
Write tests first if adding new functionality (Test-Driven Development)
Run tests locally to ensure all tests pass before committing
Format code with Black and ensure code quality
Commit changes with descriptive commit messages
Push to your fork and create a pull request

Development Workflow

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes, write tests first
# Edit files...

# Run tests to ensure everything works
python -m pytest tests/ -v

# Format code
black src/ tests/

# Commit and push
git add .
git commit -m "Add feature description"
git push origin feature/your-feature-name

Testing Guidelines

All new features should include tests
Tests should pass before submitting PRs
Use descriptive test names and clear assertions
Test both success and error cases
Ensure Meilisearch is running before running tests

Release Process

This project uses automated versioning and publishing to PyPI. The release process is designed to be simple and automated.

How Releases Work

Automated Publishing: When the version number in pyproject.toml changes on the main branch, a GitHub Action automatically:
- Builds the Python package
- Publishes it to PyPI using trusted publishing
- Creates a new release on GitHub
Version Detection: The workflow compares the current version in pyproject.toml with the previous commit to detect changes
PyPI Publishing: Uses PyPA's official publish action with trusted publishing (no manual API keys needed)

Creating a New Release

To create a new release, follow these steps:

1. Determine Version Number

Follow Semantic Versioning (MAJOR.MINOR.PATCH):

PATCH (e.g., 0.4.0 → 0.4.1): Bug fixes, documentation updates, minor improvements
MINOR (e.g., 0.4.0 → 0.5.0): New features, new MCP tools, significant enhancements
MAJOR (e.g., 0.5.0 → 1.0.0): Breaking changes, major API changes

2. Update Version and Create PR

# 1. Create a branch from latest main
git checkout main
git pull origin main
git checkout -b release/v0.5.0

# 2. Update version in pyproject.toml
# Edit the version = "0.4.0" line to your new version

# 3. Commit and push
git add pyproject.toml
git commit -m "Bump version to 0.5.0"
git push origin release/v0.5.0

# 4. Create PR and get it reviewed/merged
gh pr create --title "Release v0.5.0" --body "Bump version for release"

3. Merge to Main

Once the PR is approved and merged to main, the GitHub Action will automatically:

Detect the version change
Build the package
Publish to PyPI at https://pypi.org/p/meilisearch-mcp
Make the new version available via pip install meilisearch-mcp

4. Verify Release

After merging, verify the release:

# Check GitHub Action status
gh run list --workflow=publish.yml

# Verify on PyPI (may take a few minutes)
pip index versions meilisearch-mcp

# Test installation of new version
pip install --upgrade meilisearch-mcp

Release Workflow File

The automated release is handled by .github/workflows/publish.yml, which:

Triggers on pushes to main branch
Checks if pyproject.toml version changed
Uses Python 3.10 and official build tools
Publishes using trusted publishing (no API keys required)
Provides verbose output for debugging

Troubleshooting Releases

Release didn't trigger: Check that the version in pyproject.toml actually changed between commits

Build failed: Check the GitHub Actions logs for Python package build errors

PyPI publish failed: Verify the package name and that trusted publishing is configured properly

Version conflicts: Ensure the new version number hasn't been used before on PyPI

Development vs Production Versions

Development: Install from source using pip install -e .
Production: Install from PyPI using pip install meilisearch-mcp
Specific version: Install using pip install meilisearch-mcp==0.5.0