Meilisearch MCP Server

offiziell

Interagieren und Abfragen mit Meilisearch (Volltext- und semantische Such-API)

GitHub
192

Dokumentation

Meilisearch

Meilisearch MCP Server

Meilisearch | Meilisearch Cloud | Dokumentation | Discord

PyPI version Python Versions Tests License Downloads

⚡ Verbinde jedes LLM mit Meilisearch und verleihe deiner KI blitzschnelle Suchfunktionen! 🔍

🤔 Was ist das?

Der Meilisearch MCP Server ist ein Model Context Protocol Server, der es jedem MCP-kompatiblen Client (einschließlich Claude, OpenAI-Agenten und anderen LLMs) ermöglicht, mit Meilisearch zu interagieren. Dieser stdio-basierte Server erlaubt KI-Assistenten, Suchindizes zu verwalten, Suchen durchzuführen und deine Daten durch natürliche Konversation zu handhaben.

Warum das nutzen?

  • 🤖 Universelle Kompatibilität – Funktioniert mit jedem MCP-Client, nicht nur mit Claude
  • 🗣️ Steuerung in natürlicher Sprache – Verwalte Meilisearch durch Konversation mit jedem LLM
  • 🚀 Keine Lernkurve – Die Meilisearch-API muss nicht erlernt werden
  • 🔧 Voller Funktionszugriff – Alle Meilisearch-Fähigkeiten stehen dir zur Verfügung
  • 🔄 Dynamische Verbindungen – Wechsle spontan zwischen Meilisearch-Instanzen
  • 📡 stdio-Transport – Verwendet derzeit stdio; native Meilisearch-MCP-Unterstützung kommt bald!

✨ Hauptfunktionen

  • 📊 Index- & Dokumentenverwaltung – Erstelle, aktualisiere und verwalte Suchindizes
  • 🔍 Intelligente Suche – Suche über einzelne oder mehrere Indizes mit erweiterter Filterung
  • ⚙️ Einstellungskonfiguration – Feinabstimmung von Suchrelevanz und Leistung
  • 📈 Aufgabenüberwachung – Verfolge den Indizierungsfortschritt und Systemvorgänge
  • 🔐 API-Schlüsselverwaltung – Sichere Zugriffskontrolle
  • 🏥 Gesundheitsüberwachung – Behalte deine Meilisearch-Instanz im Auge
  • 🐍 Python-Implementierung – TypeScript-Version ebenfalls verfügbar

🚀 Schnellstart

In nur 3 Schritten einsatzbereit!

1️⃣ Paket installieren

# Using pip
pip install meilisearch-mcp

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

2️⃣ Claude Desktop konfigurieren

Füge dies zu deiner claude_desktop_config.json hinzu:

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

3️⃣ Meilisearch starten

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

# Or using Homebrew
brew install meilisearch
meilisearch

Das war's! Jetzt kannst du deinen KI-Assistenten bitten, deine Meilisearch-Daten zu durchsuchen und zu verwalten! 🎉

📚 Beispiele

💬 Sprich mit deinem KI-Assistenten ganz natürlich:

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!

🔍 Beispiel für erweiterte Suche:

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

Voraussetzungen

  • Python ≥ 3.9
  • Laufende Meilisearch-Instanz
  • MCP-kompatibler Client (Claude Desktop, OpenAI-Agenten usw.)

Von PyPI

pip install meilisearch-mcp

Aus dem Quellcode (für die Entwicklung)

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

Mit Docker

Perfekt für containerisierte Umgebungen wie n8n-Workflows!

Von 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

Aus dem Quellcode bauen

# 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 mit n8n

Für n8n-Workflows kannst du das Docker-Image direkt in deinem Setup verwenden:

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

🛠️ Was kannst du tun?

🔗 Verbindungsverwaltung
  • Aktuelle Verbindungseinstellungen anzeigen
  • Dynamisch zwischen Meilisearch-Instanzen wechseln
  • API-Schlüssel spontan aktualisieren
📁 Indexoperationen
  • Neue Indizes mit benutzerdefinierten Primärschlüsseln erstellen
  • Alle Indizes mit Statistiken auflisten
  • Indizes und ihre Daten löschen
  • Detaillierte Indexmetriken abrufen
📄 Dokumentenverwaltung
  • Dokumente hinzufügen oder aktualisieren
  • Dokumente mit Paginierung abrufen
  • Massenimport von Daten
🔍 Suchfunktionen
  • Suche mit Filtern, Sortierung und Facetten
  • Multi-Index-Suche
  • Semantische Suche mit Vektoren
  • Hybride Suche (Stichwort + semantisch)
⚙️ Einstellungen & Konfiguration
  • Ranking-Regeln konfigurieren
  • Facettierung und Filterung einrichten
  • Durchsuchbare Attribute verwalten
  • Tippfehlertoleranz anpassen
🔐 Sicherheit
  • API-Schlüssel erstellen und verwalten
  • Granulare Berechtigungen festlegen
  • Schlüsselverwendung überwachen

⚠️ Hinweis: Obwohl du Hosts und API-Schlüssel der Einfachheit halber direkt im Chat hinzufügen und aktualisieren kannst, ist dieser Ansatz in erster Linie für Entwicklungsanwendungsfälle gedacht (z. B. spontanes Verbinden mit mehreren Instanzen). Er entspricht nicht den besten MCP-Sicherheitspraktiken und sollte nicht ohne angemessene Sicherheitsvorkehrungen in Produktionsumgebungen verwendet werden.

📊 Überwachung & Gesundheit
  • Gesundheitsprüfungen
  • Systemstatistiken
  • Aufgabenüberwachung
  • Versionsinformationen

🌍 Umgebungsvariablen

Standard-Verbindungseinstellungen konfigurieren:

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

💻 Entwicklung

Entwicklungsumgebung einrichten

  1. Meilisearch starten:

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

  2. Entwicklungsabhängigkeiten installieren:

    uv pip install -r requirements-dev.txt

  3. Tests ausführen:

    python -m pytest tests/ -v

  4. Code formatieren:

    black src/ tests/

Testen mit MCP Inspector

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 Community & Support

Wir freuen uns, von dir zu hören! So erhältst du Hilfe und kannst dich vernetzen:

🤗 Mitwirken

Beiträge sind willkommen! So legst du los:

  1. Forke das Repository
  2. Erstelle deinen Feature-Branch (git checkout -b feature/amazing-feature)
  3. Schreibe Tests für deine Änderungen
  4. Nimm deine Änderungen vor und führe Tests aus
  5. Formatiere deinen Code mit black
  6. Committe deine Änderungen (git commit -m 'Add amazing feature')
  7. Pushe zu deinem Branch (git push origin feature/amazing-feature)
  8. Öffne einen Pull Request

Weitere Details findest du in unseren Richtlinien für Mitwirkende.

📦 Release-Prozess

Dieses Projekt verwendet automatisierte Versionierung und Veröffentlichung. Wenn sich die Version in pyproject.toml auf dem main-Branch ändert, wird das Paket automatisch auf PyPI veröffentlicht.

Detaillierte Anweisungen findest du im Abschnitt Release-Prozess.

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe LICENSE-Datei für Details.

Meilisearch ist eine Open-Source-Suchmaschine, die ein hervorragendes Sucherlebnis bietet.
Erfahre mehr über Meilisearch auf meilisearch.com

📖 Vollständige Dokumentation

Verfügbare Werkzeuge

Verbindungsverwaltung

  • get-connection-settings: Aktuelle Meilisearch-Verbindungs-URL und API-Schlüsselstatus anzeigen
  • update-connection-settings: URL und/oder API-Schlüssel aktualisieren, um eine Verbindung zu einer anderen Instanz herzustellen

Indexverwaltung

  • create-index: Einen neuen Index mit optionalem Primärschlüssel erstellen
  • list-indexes: Alle verfügbaren Indizes auflisten
  • delete-index: Einen vorhandenen Index und alle seine Dokumente löschen
  • get-index-metrics: Detaillierte Metriken für einen bestimmten Index abrufen

Dokumentoperationen

  • get-documents: Dokumente aus einem Index mit Paginierung abrufen
  • add-documents: Dokumente in einem Index hinzufügen oder aktualisieren

Suche

  • search: Flexible Suche über einzelne oder mehrere Indizes mit Filter- und Sortieroptionen

Einstellungsverwaltung

  • get-settings: Aktuelle Einstellungen für einen Index anzeigen
  • update-settings: Indexeinstellungen aktualisieren (Ranking, Facettierung usw.)

API-Schlüsselverwaltung

  • get-keys: Alle API-Schlüssel auflisten
  • create-key: Neuen API-Schlüssel mit bestimmten Berechtigungen erstellen
  • delete-key: Einen vorhandenen API-Schlüssel löschen

Aufgabenverwaltung

  • get-task: Informationen zu einer bestimmten Aufgabe abrufen
  • get-tasks: Aufgaben mit optionalen Filtern auflisten
  • cancel-tasks: Ausstehende oder in der Warteschlange befindliche Aufgaben abbrechen
  • delete-tasks: Abgeschlossene Aufgaben löschen

Systemüberwachung

  • health-check: Einfache Gesundheitsprüfung
  • get-health-status: Umfassender Gesundheitsstatus
  • get-version: Meilisearch-Versionsinformationen abrufen
  • get-stats: Datenbankstatistiken abrufen
  • get-system-info: Informationen auf Systemebene abrufen

Entwicklungseinrichtung

Voraussetzungen

  1. Meilisearch-Server starten:

    # 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. Entwicklungswerkzeuge installieren:

    # 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

Tests ausführen

Dieses Projekt enthält umfassende Integrationstests, die die MCP-Werkzeugfunktionalität überprüfen:

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

Wichtig: Tests erfordern eine laufende Meilisearch-Instanz auf http://localhost:7700.

Codequalität

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

Richtlinien für Mitwirkende

  1. Forken und klonen des Repositorys
  2. Entwicklungsumgebung einrichten gemäß dem obigen Abschnitt Entwicklungseinrichtung
  3. Feature-Branch erstellen von main
  4. Zuerst Tests schreiben, wenn neue Funktionalität hinzugefügt wird (Testgetriebene Entwicklung)
  5. Tests lokal ausführen, um sicherzustellen, dass alle Tests vor dem Commit bestehen
  6. Code formatieren mit Black und Codequalität sicherstellen
  7. Änderungen committen mit aussagekräftigen Commit-Nachrichten
  8. Auf deinen Fork pushen und einen Pull Request erstellen

Entwicklungsworkflow

# 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

Testrichtlinien

  • Alle neuen Funktionen sollten Tests enthalten
  • Tests sollten vor dem Einreichen von PRs bestanden werden
  • Verwende aussagekräftige Testnamen und klare Assertions
  • Teste sowohl Erfolgs- als auch Fehlerfälle
  • Stelle sicher, dass Meilisearch läuft, bevor Tests ausgeführt werden

Release-Prozess

Dieses Projekt verwendet automatisierte Versionierung und Veröffentlichung auf PyPI. Der Release-Prozess ist einfach und automatisiert gestaltet.

Wie Releases funktionieren

  1. Automatisierte Veröffentlichung: Wenn sich die Versionsnummer in pyproject.toml auf dem main-Branch ändert, führt eine GitHub Action automatisch Folgendes aus:

    • Baut das Python-Paket
    • Veröffentlicht es auf PyPI mittels Trusted Publishing
    • Erstellt ein neues Release auf GitHub

  2. Versionserkennung: Der Workflow vergleicht die aktuelle Version in pyproject.toml mit dem vorherigen Commit, um Änderungen zu erkennen

  3. PyPI-Veröffentlichung: Verwendet die offizielle Publish-Action von PyPA mit Trusted Publishing (keine manuellen API-Schlüssel erforderlich)

Ein neues Release erstellen

Um ein neues Release zu erstellen, befolge diese Schritte:

1. Versionsnummer bestimmen

Befolge Semantic Versioning (MAJOR.MINOR.PATCH):

  • PATCH (z. B. 0.4.0 → 0.4.1): Fehlerbehebungen, Dokumentationsaktualisierungen, kleinere Verbesserungen
  • MINOR (z. B. 0.4.0 → 0.5.0): Neue Funktionen, neue MCP-Werkzeuge, bedeutende Erweiterungen
  • MAJOR (z. B. 0.5.0 → 1.0.0): Breaking Changes, größere API-Änderungen
2. Version aktualisieren und PR erstellen
# 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. In Main mergen

Sobald der PR genehmigt und in main gemerged wurde, wird die GitHub Action automatisch:

  1. Die Versionsänderung erkennen
  2. Das Paket bauen
  3. Auf PyPI unter https://pypi.org/p/meilisearch-mcp veröffentlichen
  4. Die neue Version über pip install meilisearch-mcp verfügbar machen
4. Release überprüfen

Überprüfe nach dem Mergen das 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-Datei

Das automatisierte Release wird von .github/workflows/publish.yml gehandhabt, welches:

  • Bei Pushes auf den main-Branch ausgelöst wird
  • Prüft, ob sich die Version in pyproject.toml geändert hat
  • Python 3.10 und offizielle Build-Werkzeuge verwendet
  • Mittels Trusted Publishing veröffentlicht (keine API-Schlüssel erforderlich)
  • Ausführliche Ausgabe zum Debuggen bereitstellt

Fehlerbehebung bei Releases

Release wurde nicht ausgelöst: Überprüfe, ob sich die Version in pyproject.toml tatsächlich zwischen den Commits geändert hat

Build fehlgeschlagen: Überprüfe die GitHub Actions-Protokolle auf Fehler beim Python-Paketbau

PyPI-Veröffentlichung fehlgeschlagen: Überprüfe den Paketnamen und ob Trusted Publishing korrekt konfiguriert ist

Versionskonflikte: Stelle sicher, dass die neue Versionsnummer auf PyPI noch nicht verwendet wurde

Entwicklungs- vs. Produktionsversionen

  • Entwicklung: Installation aus dem Quellcode mit pip install -e .
  • Produktion: Installation von PyPI mit pip install meilisearch-mcp
  • Bestimmte Version: Installation mit pip install meilisearch-mcp==0.5.0