Meilisearch

официальный

Взаимодействие и запросы к Meilisearch (API полнотекстового и семантического поиска)

Что можно делать с Meilisearch MCP?

  • Управление индексами — Создавайте, просматривайте и удаляйте поисковые индексы, в том числе задавайте пользовательский первичный ключ при создании индекса.
  • Работа с документами — Добавляйте документы в индекс или обновляйте их, а также получайте их с постраничной разбивкой.
  • Поиск — Выполняйте поиск по одному или нескольким индексам с фильтрами, сортировкой и фасетами.
  • Управление настройками — Просматривайте и обновляйте настройки индекса, например правила ранжирования, фасетирование и атрибуты, доступные для поиска.
  • Мониторинг задач и состояния — Проверяйте состояние экземпляра, версию и статистику, а также отслеживайте или отменяйте задачи индексирования.
  • Управление API-ключами — Просматривайте, создавайте и удаляйте API-ключи с определёнными разрешениями.

Документация

Meilisearch

Сервер MCP Meilisearch

Meilisearch | Meilisearch Cloud | Документация | Discord

PyPI version Python Versions Tests License Downloads

[!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

💻 Разработка

Настройка среды разработки

  1. Запустите Meilisearch:

    docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
    
  2. Установите зависимости для разработки:

    uv pip install -r requirements-dev.txt
    
  3. Запустите тесты:

    python -m pytest tests/ -v
    
  4. Отформатируйте код:

    black src/ tests/
    

Тестирование с помощью MCP Inspector

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 Сообщество и поддержка

Будем рады вашим отзывам! Вот как получить помощь и связаться с нами:

🤗 Участие в разработке

Мы приветствуем ваш вклад! Вот как начать:

  1. Создайте форк репозитория
  2. Создайте ветку для своей функции (git checkout -b feature/amazing-feature)
  3. Напишите тесты для своих изменений
  4. Внесите изменения и запустите тесты
  5. Отформатируйте код с помощью black
  6. Зафиксируйте изменения (git commit -m 'Add amazing feature')
  7. Отправьте изменения в свою ветку (git push origin feature/amazing-feature)
  8. Создайте 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: Получение информации о версии Meilisearch
  • get-stats: Получение статистики базы данных
  • get-system-info: Получение информации на уровне системы

Настройка среды разработки

Предварительные требования

  1. Запустите сервер 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
    
  2. Установите инструменты для разработки:

    # 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/

Руководство по участию в разработке

  1. Создайте форк и клонируйте репозиторий
  2. Настройте среду разработки, следуя приведённому выше разделу «Настройка среды разработки»
  3. Создайте ветку для функции на основе main
  4. Сначала напишите тесты, если добавляете новую функциональность (разработка через тестирование)
  5. Запустите тесты локально, чтобы убедиться, что все они проходят перед фиксацией изменений
  6. Отформатируйте код с помощью Black и проверьте его качество
  7. Зафиксируйте изменения с описательными сообщениями коммитов
  8. Отправьте изменения в свой форк и создайте 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. Процесс выпуска прост и автоматизирован.

Как проходят выпуски

  1. Автоматическая публикация: при изменении номера версии в pyproject.toml в ветке main GitHub Action автоматически:

    • Собирает пакет Python
    • Публикует его в PyPI с помощью доверенной публикации
    • Создаёт новый выпуск на GitHub
  2. Определение версии: рабочий процесс сравнивает текущую версию в pyproject.toml с версией из предыдущего коммита, чтобы обнаружить изменения

  3. Публикация в 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 автоматически:

  1. Определите изменение версии
  2. Соберите пакет
  3. Опубликуйте пакет в PyPI по адресу https://pypi.org/p/meilisearch-mcp
  4. Сделайте новую версию доступной через 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