Meilisearch MCP Server

官方

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

GitHub

192

文档

Meilisearch MCP 服务器

Meilisearch | Meilisearch Cloud | 文档 | Discord

⚡ 将任何 LLM 连接到 Meilisearch，用闪电般的搜索能力为你的 AI 赋能！🔍

🤔 这是什么？

Meilisearch MCP 服务器是一个模型上下文协议服务器，它使任何兼容 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 - 与社区聊天
🐛 报告问题 - 发现 bug？告诉我们！
💡 功能请求 - 有想法？我们洗耳恭听！
📖 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 安装