Meilisearch
официальныйВзаимодействие и запросы к Meilisearch (API полнотекстового и семантического поиска)
Что можно делать с Meilisearch MCP?
- Управление индексами — Создавайте, просматривайте и удаляйте поисковые индексы, в том числе задавайте пользовательский первичный ключ при создании индекса.
- Работа с документами — Добавляйте документы в индекс или обновляйте их, а также получайте их с постраничной разбивкой.
- Поиск — Выполняйте поиск по одному или нескольким индексам с фильтрами, сортировкой и фасетами.
- Управление настройками — Просматривайте и обновляйте настройки индекса, например правила ранжирования, фасетирование и атрибуты, доступные для поиска.
- Мониторинг задач и состояния — Проверяйте состояние экземпляра, версию и статистику, а также отслеживайте или отменяйте задачи индексирования.
- Управление API-ключами — Просматривайте, создавайте и удаляйте API-ключи с определёнными разрешениями.
Документация
Сервер MCP Meilisearch
Meilisearch | Meilisearch Cloud | Документация | Discord
[!WARNING] Этот пакет устарел. Вместо него используйте встроенный сервер MCP Meilisearch.
Теперь Meilisearch включает встроенный сервер MCP (Meilisearch v1.54 и новее). Он доступен по маршруту
/mcpвашего экземпляра через HTTP, поэтому устанавливать или запускать этот пакет Python больше не нужно.👉 Следуйте руководству по MCP Meilisearch, чтобы настроить его.
Этот репозиторий — локальная оболочка stdio, созданная до появления встроенной поддержки. Он больше не поддерживается и сохранён только для существующих пользователей.
⚡ Подключите любую LLM к Meilisearch и расширьте возможности ИИ благодаря молниеносному поиску! 🔍
🤔 Что это?
Сервер MCP Meilisearch — это сервер Model Context Protocol, который позволяет любому совместимому с MCP клиенту (включая Claude, агентов OpenAI и другие LLM) взаимодействовать с Meilisearch. Этот сервер на основе stdio позволяет ИИ-ассистентам управлять поисковыми индексами, выполнять поиск и работать с вашими данными в ходе обычного диалога.
Зачем это нужно?
- 🤖 Универсальная совместимость — работает с любым клиентом MCP, а не только с Claude
- 🗣️ Управление на естественном языке — управляйте Meilisearch в диалоге с любой LLM
- 🚀 Не нужно ничего изучать — не требуется изучать API Meilisearch
- 🔧 Полный доступ к функциям — все возможности Meilisearch у вас под рукой
- 🔄 Динамическое подключение — переключайтесь между экземплярами Meilisearch на лету
- 📡 Транспорт stdio — использует только stdio; для HTTP используйте встроенный сервер MCP Meilisearch
✨ Основные возможности
- 📊 Управление индексами и документами — создавайте и обновляйте поисковые индексы и управляйте ими
- 🔍 Умный поиск — ищите в одном или нескольких индексах с расширенной фильтрацией
- ⚙️ Настройка параметров — точно настраивайте релевантность и производительность поиска
- 📈 Мониторинг задач — отслеживайте ход индексации и системные операции
- 🔐 Управление API-ключами — безопасный контроль доступа
- 🏥 Мониторинг состояния — следите за состоянием экземпляра Meilisearch
- 🧱 Структурированный вывод инструментов — каждый инструмент, возвращающий данные, предоставляет
structuredContentвместе с текстом согласно последней спецификации MCP - 🔀 Современный стек MCP — создан на основе официального MCP Python SDK v2 (спецификация 2026-07-28), обратно совместим со старыми клиентами MCP
- 🐍 Реализация на Python — также доступна версия на TypeScript
🚀 Быстрый старт
Начните работу всего за 3 шага!
1️⃣ Установите пакет
# Using pip
pip install meilisearch-mcp
# Or using uvx (recommended)
uvx -n meilisearch-mcp
2️⃣ Настройте Claude Desktop
Добавьте это в claude_desktop_config.json:
{
"mcpServers": {
"meilisearch": {
"command": "uvx",
"args": ["-n", "meilisearch-mcp"]
}
}
}
3️⃣ Запустите Meilisearch
# Using Docker (recommended)
docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
# Or using Homebrew
brew install meilisearch
meilisearch
Готово! Теперь вы можете попросить ИИ-ассистента искать и управлять данными Meilisearch! 🎉
📚 Примеры
💬 Общайтесь с ИИ-ассистентом на естественном языке:
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!
🔍 Пример расширенного поиска:
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
🔧 Установка
Предварительные требования
- Python ≥ 3.10
- Запущенный экземпляр Meilisearch
- Совместимый с MCP клиент (Claude Desktop, агенты OpenAI и т. д.)
Из PyPI
pip install meilisearch-mcp
Из исходного кода (для разработки)
# 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 .
С помощью Docker
Отлично подходит для контейнеризированных сред, например рабочих процессов n8n!
Из 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 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
Интеграция с n8n
Для рабочих процессов n8n можно напрямую использовать образ Docker в своей конфигурации:
meilisearch-mcp:
image: getmeili/meilisearch-mcp:latest
environment:
- MEILI_HTTP_ADDR=http://meilisearch:7700
- MEILI_MASTER_KEY=masterKey
🛠️ Что можно делать?
🔗 Управление подключениями
- Просматривать текущие параметры подключения
- Динамически переключаться между экземплярами Meilisearch
- Обновлять API-ключи на лету
📁 Операции с индексами
- Создавать индексы с пользовательскими первичными ключами
- Просматривать список всех индексов и их статистику
- Удалять индексы и содержащиеся в них данные
- Получать подробные метрики индексов
📄 Управление документами
- Добавлять и обновлять документы
- Получать документы с постраничной навигацией
- Импортировать данные пакетами
🔍 Возможности поиска
- Искать с фильтрами, сортировкой и фасетами
- Выполнять поиск по нескольким индексам
- Выполнять семантический поиск с векторами
- Выполнять гибридный поиск (по ключевым словам и семантический)
⚙️ Параметры и конфигурация
- Настраивать правила ранжирования
- Настраивать фасетный поиск и фильтрацию
- Управлять атрибутами, доступными для поиска
- Настраивать допуск к опечаткам
🔐 Безопасность
- Создавать API-ключи и управлять ими
- Настраивать детализированные разрешения
- Отслеживать использование ключей
⚠️ Примечание: для удобства можно добавлять и обновлять хосты и API-ключи прямо в чате, однако этот подход предназначен главным образом для разработки (например, для переключения между несколькими экземплярами на лету). Он не соответствует лучшим практикам безопасности MCP и не должен использоваться в производственной среде без надлежащих мер защиты.
📊 Мониторинг и состояние
- Проверка состояния
- Системная статистика
- Мониторинг задач
- Информация о версии
🌍 Переменные окружения
Настройте параметры подключения по умолчанию:
MEILI_HTTP_ADDR=http://localhost:7700 # Default Meilisearch URL
MEILI_MASTER_KEY=your_master_key # Optional: Default API key
💻 Разработка
Настройка среды разработки
-
Запустите Meilisearch:
docker run -d -p 7700:7700 getmeili/meilisearch:v1.28 -
Установите зависимости для разработки:
uv pip install -r requirements-dev.txt -
Запустите тесты:
python -m pytest tests/ -v -
Отформатируйте код:
black src/ tests/
Тестирование с помощью MCP Inspector
npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp
🤝 Сообщество и поддержка
Будем рады вашим отзывам! Вот как получить помощь и связаться с нами:
- 💬 Присоединяйтесь к нашему Discord — общайтесь с сообществом
- 🐛 Сообщите о проблеме — нашли ошибку? Расскажите нам!
- 💡 Предложите функцию — есть идея? Мы готовы выслушать!
- 📖 Документация Meilisearch — узнайте больше о Meilisearch
🤗 Участие в разработке
Мы приветствуем ваш вклад! Вот как начать:
- Создайте форк репозитория
- Создайте ветку для своей функции (
git checkout -b feature/amazing-feature) - Напишите тесты для своих изменений
- Внесите изменения и запустите тесты
- Отформатируйте код с помощью
black - Зафиксируйте изменения (
git commit -m 'Add amazing feature') - Отправьте изменения в свою ветку (
git push origin feature/amazing-feature) - Создайте Pull Request
Подробнее см. в руководстве по участию в разработке.
📦 Процесс выпуска
В этом проекте используются автоматическое управление версиями и публикация. При изменении версии в pyproject.toml в ветке main пакет автоматически публикуется в PyPI.
Подробные инструкции см. в разделе Процесс выпуска.
📄 Лицензия
Этот проект распространяется по лицензии MIT. Подробности см. в файле LICENSE.
Meilisearch — это поисковая система с открытым исходным кодом, обеспечивающая удобный поиск.
Подробнее о Meilisearch: meilisearch.com
📖 Полная документация
Доступные инструменты
Управление подключениями
get-connection-settings: Просмотр текущего URL подключения к Meilisearch и состояния API-ключаupdate-connection-settings: Обновление URL и/или API-ключа для подключения к другому экземпляру
Управление индексами
create-index: Создание индекса с необязательным первичным ключомlist-indexes: Просмотр списка всех доступных индексовdelete-index: Удаление существующего индекса и всех его документовget-index-metrics: Получение подробных метрик для указанного индекса
Операции с документами
get-documents: Получение документов из индекса с постраничной навигациейadd-documents: Добавление или обновление документов в индексе
Поиск
search: Гибкий поиск по одному или нескольким индексам с возможностью фильтрации и сортировки
Управление параметрами
get-settings: Просмотр текущих параметров индексаupdate-settings: Обновление параметров индекса (ранжирование, фасетный поиск и т. д.)
Управление API-ключами
get-keys: Просмотр списка всех API-ключейcreate-key: Создание API-ключа с заданными разрешениямиdelete-key: Удаление существующего API-ключа
Управление задачами
get-task: Получение информации об указанной задачеget-tasks: Просмотр списка задач с необязательными фильтрамиcancel-tasks: Отмена ожидающих или поставленных в очередь задач
Мониторинг системы
health-check: Базовая проверка состоянияget-health-status: Подробная информация о состоянииget-version: Получение информации о версии Meilisearchget-stats: Получение статистики базы данныхget-system-info: Получение информации на уровне системы
Настройка среды разработки
Предварительные требования
-
Запустите сервер Meilisearch:
# Using Docker (recommended for development) docker run -d -p 7700:7700 getmeili/meilisearch:v1.28 # Or using brew (macOS) brew install meilisearch meilisearch # Or download from https://github.com/meilisearch/meilisearch/releases -
Установите инструменты для разработки:
# 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
Запуск тестов
В проект входят комплексные интеграционные тесты, проверяющие работу инструментов MCP:
# 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/
Важно: для тестов требуется запущенный экземпляр Meilisearch на http://localhost:7700.
Качество кода
# 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/
Руководство по участию в разработке
- Создайте форк и клонируйте репозиторий
- Настройте среду разработки, следуя приведённому выше разделу «Настройка среды разработки»
- Создайте ветку для функции на основе
main - Сначала напишите тесты, если добавляете новую функциональность (разработка через тестирование)
- Запустите тесты локально, чтобы убедиться, что все они проходят перед фиксацией изменений
- Отформатируйте код с помощью Black и проверьте его качество
- Зафиксируйте изменения с описательными сообщениями коммитов
- Отправьте изменения в свой форк и создайте pull request
Рабочий процесс разработки
# 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
Рекомендации по тестированию
- Все новые функции должны сопровождаться тестами
- Перед отправкой PR тесты должны проходить
- Используйте понятные имена тестов и ясные проверки
- Проверяйте как успешные сценарии, так и ошибки
- Перед запуском тестов убедитесь, что Meilisearch запущен
Процесс выпуска
В этом проекте используются автоматическое управление версиями и публикация в PyPI. Процесс выпуска прост и автоматизирован.
Как проходят выпуски
-
Автоматическая публикация: при изменении номера версии в
pyproject.tomlв веткеmainGitHub Action автоматически:- Собирает пакет Python
- Публикует его в PyPI с помощью доверенной публикации
- Создаёт новый выпуск на GitHub
-
Определение версии: рабочий процесс сравнивает текущую версию в
pyproject.tomlс версией из предыдущего коммита, чтобы обнаружить изменения -
Публикация в PyPI: используется официальное действие публикации PyPA с доверенной публикацией (ручные API-ключи не нужны)
Создание нового выпуска
Чтобы создать новый выпуск, выполните следующие действия:
1. Определите номер версии
Следуйте семантическому версионированию (MAJOR.MINOR.PATCH):
- PATCH (например, 0.4.0 → 0.4.1): исправления ошибок, обновления документации, небольшие улучшения
- MINOR (например, 0.4.0 → 0.5.0): новые функции, новые инструменты MCP, значительные улучшения
- MAJOR (например, 0.5.0 → 1.0.0): несовместимые изменения, значительные изменения API
2. Обновите версию и создайте 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. Слияние в Main
После одобрения и слияния PR в main GitHub Action автоматически:
- Определите изменение версии
- Соберите пакет
- Опубликуйте пакет в PyPI по адресу https://pypi.org/p/meilisearch-mcp
- Сделайте новую версию доступной через
pip install meilisearch-mcp
4. Проверьте выпуск
После слияния проверьте выпуск:
# 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
Файл рабочего процесса выпуска
Автоматический выпуск выполняется с помощью .github/workflows/publish.yml, который:
- Запускается при отправке изменений в ветку
main - Проверяет, изменилась ли версия
pyproject.toml - Использует Python 3.10 и официальные инструменты сборки
- Публикует пакет с помощью доверенной публикации (ключи API не требуются)
- Выводит подробную информацию для отладки
Устранение неполадок при выпуске
Выпуск не запустился: Проверьте, действительно ли изменилась версия в pyproject.toml между коммитами
Сборка завершилась с ошибкой: Проверьте журналы GitHub Actions на наличие ошибок сборки пакета Python
Публикация в PyPI завершилась с ошибкой: Проверьте имя пакета и правильность настройки доверенной публикации
Конфликты версий: Убедитесь, что новый номер версии ещё не использовался в PyPI
Версии для разработки и производства
- Разработка: Установите из исходного кода с помощью
pip install -e . - Производство: Установите из PyPI с помощью
pip install meilisearch-mcp - Определённая версия: Установите с помощью
pip install meilisearch-mcp==0.5.0