Meilisearch

官方

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

GitHub

198

你可以用 Meilisearch MCP 做什麼？

索引管理 — 建立、列出及刪除搜尋索引，包括在建立索引時設定自訂主索引鍵。
文件處理 — 在索引中新增或更新文件，並透過分頁擷取文件。
搜尋 — 使用篩選條件、排序和分面，在一個或多個索引中執行搜尋。
設定管理 — 檢視及更新索引設定，例如排名規則、分面和可搜尋屬性。
任務與健康狀態監控 — 檢查執行個體的健康狀態、版本和統計資料，並追蹤或取消索引任務。
API 金鑰管理 — 列出、建立及刪除具有特定權限的 API 金鑰。

文件

Meilisearch MCP Server

Meilisearch | Meilisearch Cloud | 文件 | Discord

[!WARNING] 此套件已棄用。請改用原生 Meilisearch MCP server。

Meilisearch 現在內建 MCP server（Meilisearch v1.54 及更新版本）。它會透過 HTTP 在您執行個體的 /mcp 路由上提供服務，因此您不再需要安裝或執行此 Python 套件。

👉 請參閱 Meilisearch MCP 指南進行設定。

此儲存庫是在原生支援推出前建立的本機 stdio 包裝程式。目前已不再積極維護，僅供現有使用者使用。

⚡ 將任何 LLM 連接至 Meilisearch，以閃電般快速的搜尋功能強化您的 AI！🔍

🤔 這是什麼？

Meilisearch MCP Server 是一種 Model Context Protocol server，可讓任何相容 MCP 的用戶端（包括 Claude、OpenAI agents 和其他 LLM）與 Meilisearch 互動。這個以 stdio 為基礎的 server 可讓 AI 助理透過自然對話管理搜尋索引、執行搜尋並處理您的資料。

為什麼要使用？

🤖 通用相容性 - 可搭配任何 MCP 用戶端，不限於 Claude
🗣️ 自然語言控制 - 透過與任何 LLM 對話來管理 Meilisearch
🚀 零學習門檻 - 無須學習 Meilisearch 的 API
🔧 完整功能存取 - Meilisearch 的所有功能盡在掌握
🔄 動態連線 - 隨時切換不同的 Meilisearch 執行個體
📡 stdio 傳輸 - 僅使用 stdio；如需 HTTP，請使用原生 Meilisearch MCP server

✨ 主要功能

📊 索引與文件管理 - 建立、更新及管理搜尋索引
🔍 智慧搜尋 - 使用進階篩選功能搜尋單一或多個索引
⚙️ 設定組態 - 微調搜尋相關性與效能
📈 工作監控 - 追蹤索引進度與系統作業
🔐 API 金鑰管理 - 安全存取控制
🏥 健康狀態監控 - 隨時掌握 Meilisearch 執行個體的狀態
🧱 結構化工具輸出 - 根據最新 MCP 規格，每個傳回資料的工具都會在文字之外提供 structuredContent
🔀 現代化 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

完成！現在您可以請 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.10
正在執行的 Meilisearch 執行個體
相容 MCP 的用戶端（Claude Desktop、OpenAI agents 等）

從 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 金鑰

📁 索引操作

使用自訂主索引鍵建立新索引
列出所有索引及其統計資料
刪除索引及其資料
取得詳細的索引指標

📄 文件管理

新增或更新文件
以分頁方式擷取文件
批次匯入資料

🔍 搜尋功能

使用篩選條件、排序和 facet 進行搜尋
多索引搜尋
使用向量進行語意搜尋
混合搜尋（關鍵字 + 語意）

⚙️ 設定與組態

設定排名規則
設定 facet 與篩選
管理可搜尋屬性
自訂錯字容忍度

🔐 安全性

建立及管理 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

如需詳細資訊，請參閱貢獻指南。

📦 發佈流程

此專案使用自動化版本管理與發佈。當 main 分支上的 pyproject.toml 變更時，套件會自動發佈至 PyPI。

詳細說明請參閱發佈流程一節。

📄 授權條款

此專案採用 MIT License 授權 - 詳情請參閱 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：更新索引設定（排名、facet 等）

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：取得系統層級資訊

開發環境設定

先決條件

啟動 Meilisearch server：

# 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 並 clone 儲存庫
依照上方「開發環境設定」一節設定開發環境
從 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。發佈流程設計得簡單且自動化。

發佈流程說明

自動發佈：當 main 分支上的 pyproject.toml 版本號變更時，GitHub Action 會自動：
- 建置 Python 套件
- 使用受信任發佈功能將套件發佈至 PyPI
- 在 GitHub 建立新版本
版本偵測：工作流程會比較 pyproject.toml 中的目前版本與前一次提交，以偵測變更
PyPI 發佈：使用 PyPA 官方發佈 action 與受信任發佈功能（不需要手動設定 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 安裝