<div align="center">
<img src="https://github.com/meilisearch/meilisearch/blob/main/assets/logo.svg" alt="Meilisearch" width="200" height="200" />
</div>
<h1 align="center">Meilisearch MCP Server</h1>
<h4 align="center">
<a href="https://github.com/meilisearch/meilisearch">Meilisearch</a> |
<a href="https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-mcp">Meilisearch Cloud</a> |
<a href="https://www.meilisearch.com/docs">Documentation</a> |
<a href="https://discord.meilisearch.com">Discord</a>
</h4>
<p align="center">
<a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/v/meilisearch-mcp.svg" alt="PyPI version"></a>
<a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/pyversions/meilisearch-mcp.svg" alt="Python Versions"></a>
<a href="https://github.com/meilisearch/meilisearch-mcp/actions"><img src="https://github.com/meilisearch/meilisearch-mcp/workflows/Test%20and%20Lint/badge.svg" alt="Tests"></a>
<a href="https://github.com/meilisearch/meilisearch-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="License"></a>
<a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/dm/meilisearch-mcp" alt="Downloads"></a>
</p>
<p align="center">⚡ Connect any LLM to Meilisearch and supercharge your AI with lightning-fast search capabilities! 🔍</p>
## 🤔 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](https://github.com/devlimelabs/meilisearch-ts-mcp)
## 🚀 Quick Start
Get up and running in just 3 steps!
### 1️⃣ Install the package
```bash
# 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`:
```json
{
"mcpServers": {
"meilisearch": {
"command": "uvx",
"args": ["-n", "meilisearch-mcp"]
}
}
}
```
### 3️⃣ Start Meilisearch
```bash
# 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
```bash
pip install meilisearch-mcp
```
### From Source (for development)
```bash
# 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
```bash
# 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
```bash
# 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:
```yaml
meilisearch-mcp:
image: getmeili/meilisearch-mcp:latest
environment:
- MEILI_HTTP_ADDR=http://meilisearch:7700
- MEILI_MASTER_KEY=masterKey
```
## 🛠️ What Can You Do?
<details>
<summary><b>🔗 Connection Management</b></summary>
- View current connection settings
- Switch between Meilisearch instances dynamically
- Update API keys on the fly
</details>
<details>
<summary><b>📁 Index Operations</b></summary>
- Create new indices with custom primary keys
- List all indices with stats
- Delete indices and their data
- Get detailed index metrics
</details>
<details>
<summary><b>📄 Document Management</b></summary>
- Add or update documents
- Retrieve documents with pagination
- Bulk import data
</details>
<details>
<summary><b>🔍 Search Capabilities</b></summary>
- Search with filters, sorting, and facets
- Multi-index search
- Semantic search with vectors
- Hybrid search (keyword + semantic)
</details>
<details>
<summary><b>⚙️ Settings & Configuration</b></summary>
- Configure ranking rules
- Set up faceting and filtering
- Manage searchable attributes
- Customize typo tolerance
</details>
<details>
<summary><b>🔐 Security</b></summary>
- Create and manage API keys
- Set granular permissions
- Monitor key usage
</details>
<details>
<summary><b>📊 Monitoring & Health</b></summary>
- Health checks
- System statistics
- Task monitoring
- Version information
</details>
## 🌍 Environment Variables
Configure default connection settings:
```bash
MEILI_HTTP_ADDR=http://localhost:7700 # Default Meilisearch URL
MEILI_MASTER_KEY=your_master_key # Optional: Default API key
```
## 💻 Development
### Setting Up Development Environment
1. **Start Meilisearch**:
```bash
docker run -d -p 7700:7700 getmeili/meilisearch:v1.6
```
2. **Install Development Dependencies**:
```bash
uv pip install -r requirements-dev.txt
```
3. **Run Tests**:
```bash
python -m pytest tests/ -v
```
4. **Format Code**:
```bash
black src/ tests/
```
### Testing with MCP Inspector
```bash
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](https://discord.meilisearch.com) - Chat with the community
- 🐛 [Report Issues](https://github.com/meilisearch/meilisearch-mcp/issues) - Found a bug? Let us know!
- 💡 [Feature Requests](https://github.com/meilisearch/meilisearch-mcp/issues) - Have an idea? We're listening!
- 📖 [Meilisearch Docs](https://www.meilisearch.com/docs) - Learn more about Meilisearch
## 🤗 Contributing
We welcome contributions! Here's how to get started:
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Write tests for your changes
4. Make your changes and run tests
5. Format your code with `black`
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to your branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
See our [Contributing Guidelines](#contributing-1) 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](#release-process-1) section for detailed instructions.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
<p align="center">
<b>Meilisearch</b> is an open-source search engine that offers a delightful search experience.<br>
Learn more about Meilisearch at <a href="https://www.meilisearch.com">meilisearch.com</a>
</p>
---
<details>
<summary><h2>📖 Full Documentation</h2></summary>
### 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
1. **Start Meilisearch server**:
```bash
# 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
```
2. **Install development tools**:
```bash
# 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:
```bash
# 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
```bash
# 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
1. **Fork and clone** the repository
2. **Set up development environment** following the Development Setup section above
3. **Create a feature branch** from `main`
4. **Write tests first** if adding new functionality (Test-Driven Development)
5. **Run tests locally** to ensure all tests pass before committing
6. **Format code** with Black and ensure code quality
7. **Commit changes** with descriptive commit messages
8. **Push to your fork** and create a pull request
### Development Workflow
```bash
# 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
1. **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
2. **Version Detection**: The workflow compares the current version in `pyproject.toml` with the previous commit to detect changes
3. **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](https://semver.org/) (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
```bash
# 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:
1. Detect the version change
2. Build the package
3. Publish to PyPI at https://pypi.org/p/meilisearch-mcp
4. Make the new version available via `pip install meilisearch-mcp`
##### 4. Verify Release
After merging, verify the release:
```bash
# 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`
</details>