Meilisearch MCP Server

官方

與 Meilisearch 互動及查詢（全文與語意搜尋 API）

GitHub

192

文件

Meilisearch MCP 伺服器

Meilisearch | Meilisearch Cloud | 文件 | Discord

⚡ 將任何 LLM 連接到 Meilisearch，用閃電般的搜尋能力為你的 AI 注入超能力！🔍

🤔 這是什麼？

Meilisearch MCP 伺服器是一個模型上下文協定 (Model Context Protocol) 伺服器，能讓任何相容 MCP 的客戶端（包括 Claude、OpenAI 代理程式及其他 LLM）與 Meilisearch 互動。這個基於 stdio 的伺服器讓 AI 助理能夠透過自然對話來管理搜尋索引、執行搜尋並處理你的資料。

為什麼要使用它？

🤖 通用相容性 - 適用於任何 MCP 客戶端，不僅限於 Claude
🗣️ 自然語言控制 - 透過與任何 LLM 對話來管理 Meilisearch
🚀 零學習曲線 - 無需學習 Meilisearch 的 API
🔧 完整功能存取 - 所有 Meilisearch 功能盡在掌握
🔄 動態連線 - 隨時切換不同的 Meilisearch 實例
📡 stdio 傳輸 - 目前使用 stdio；即將推出原生 Meilisearch MCP 支援！

✨ 主要功能

📊 索引與文件管理 - 建立、更新及管理搜尋索引
🔍 智慧搜尋 - 跨單一或多個索引進行搜尋，並支援進階篩選
⚙️ 設定組態 - 微調搜尋相關性與效能
📈 任務監控 - 追蹤索引進度與系統操作
🔐 API 金鑰管理 - 安全的存取控制
🏥 健康監控 - 隨時掌握 Meilisearch 實例狀態
🐍 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

就是這樣！現在你可以要求 AI 助理搜尋並管理你的 Meilisearch 資料了！🎉

📚 範例

💬 自然地與 AI 助理對話：

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.9
正在運行的 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

🤗 貢獻

我們歡迎貢獻！以下是入門方式：

Fork 此儲存庫
建立你的功能分支 (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.com 深入了解 Meilisearch

📖 完整文件

可用工具

連線管理

get-connection-settings：檢視目前的 Meilisearch 連線 URL 和 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：取消待處理或已排入佇列的任務
delete-tasks：刪除已完成的任務

系統監控

health-check：基本健康檢查
get-health-status：全面的健康狀態
get-version：取得 Meilisearch 版本資訊
get-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/

重要：測試需要一個在 http://localhost:7700 上運行的 Meilisearch 實例。

程式碼品質

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

貢獻指南

Fork 並複製儲存庫
依照上方開發設定章節設定開發環境
從 main 建立功能分支
先撰寫測試如果要新增功能（測試驅動開發）
在提交前於本地執行測試，確保所有測試通過
使用 Black 格式化程式碼並確保程式碼品質
提交變更，使用描述性的提交訊息
推送到你的 fork 並建立 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 中的版本號在 main 分支上變更時，GitHub 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 . 從原始碼安裝
正式：使用 pip install meilisearch-mcp 從 PyPI 安裝
特定版本：使用 pip install meilisearch-mcp==0.5.0 安裝