Meilisearch

官方

与 Meilisearch 交互并查询（全文及语义搜索 API）

GitHub

198

你可以用 Meilisearch MCP 做什么？

索引管理 — 创建、列出和删除搜索索引，包括在创建索引时设置自定义主键。
文档处理 — 在索引中添加或更新文档，并通过分页检索文档。
搜索 — 在一个或多个索引中执行搜索，并使用筛选、排序和分面。
设置管理 — 查看和更新索引设置，例如排序规则、分面和可搜索属性。
任务与健康监控 — 检查实例健康状况、版本和统计信息，并跟踪或取消索引任务。
API 密钥管理 — 列出、创建和删除具有特定权限的 API 密钥。

文档

Meilisearch MCP 服务器

Meilisearch | Meilisearch Cloud | 文档 | Discord

[!WARNING] 此软件包已弃用。请改用原生 Meilisearch MCP 服务器。

Meilisearch 现已内置 MCP 服务器（Meilisearch v1.54 及更高版本）。它通过 HTTP 在实例的 /mcp 路由上提供，因此您不再需要安装或运行此 Python 软件包。

👉 请按照 Meilisearch MCP 指南进行设置。

此代码库是在原生支持推出之前构建的本地 stdio 封装程序。它不再积极维护，仅为现有用户保留。

⚡ 将任何 LLM 连接到 Meilisearch，借助闪电般快速的搜索能力为您的 AI 增强动力！🔍

🤔 这是什么？

Meilisearch MCP 服务器是一个模型上下文协议服务器，可让任何兼容 MCP 的客户端（包括 Claude、OpenAI 智能体和其他 LLM）与 Meilisearch 交互。这个基于 stdio 的服务器允许 AI 助手通过自然对话管理搜索索引、执行搜索并处理您的数据。

为什么要使用它？

🤖 通用兼容性 - 可与任何 MCP 客户端配合使用，而不仅限于 Claude
🗣️ 自然语言控制 - 通过与任何 LLM 对话来管理 Meilisearch
🚀 零学习成本 - 无需学习 Meilisearch API
🔧 全面功能访问 - 尽享 Meilisearch 的所有功能
🔄 动态连接 - 随时切换 Meilisearch 实例
📡 stdio 传输 - 仅使用 stdio；如需 HTTP，请使用原生 Meilisearch MCP 服务器

✨ 主要功能

📊 索引和文档管理 - 创建、更新和管理搜索索引
🔍 智能搜索 - 使用高级筛选条件跨单个或多个索引搜索
⚙️ 设置配置 - 微调搜索相关性和性能
📈 任务监控 - 跟踪索引进度和系统操作
🔐 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 智能体等）

从 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：取消待处理或已排队的任务

系统监控

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 安装