Meilisearch MCP 服务器

一个用于通过Claude等LLM接口与Meilisearch交互的模型上下文协议（MCP）服务器。

功能

索引和文档管理
设置配置和管理
任务监控和API密钥管理
内置日志和监控工具
动态连接配置以切换Meilisearch实例
在单个或多个索引上进行智能搜索
这是一个Python实现，如果你需要在浏览器中使用Meilisearch MCP服务器，有Typescript集成

安装

# 克隆仓库
git clone <repository_url>
cd meilisearch-mcp

# 创建虚拟环境并安装
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
uv pip install -e .

# 安装开发依赖（用于测试和开发）
uv pip install -r requirements-dev.txt

要求

Python ≥ 3.9
运行的Meilisearch实例
Node.js（用于使用MCP Inspector进行测试）

开发设置

先决条件

启动Meilisearch服务器：

# 使用Docker（推荐用于开发）
docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

# 或者使用brew（macOS）
brew install meilisearch
meilisearch

# 或者从https://github.com/meilisearch/meilisearch/releases下载

安装开发工具：

# 安装uv用于Python包管理
pip install uv

# 安装Node.js用于MCP Inspector测试
# 访问https://nodejs.org/或使用你的包管理器

运行测试

该项目包括全面的集成测试，验证MCP工具的功能：

# 运行所有测试
python -m pytest tests/ -v

# 运行特定测试文件
python -m pytest tests/test_mcp_client.py -v

# 运行测试并生成覆盖率报告
python -m pytest --cov=src tests/

# 在监视模式下运行测试（需要pytest-watch）
pytest-watch tests/

重要提示：测试需要在http://localhost:7700上运行Meilisearch实例。测试将：

创建具有唯一名称的临时测试索引
端到端测试所有MCP工具
自动清理测试数据
验证错误处理和边缘情况

代码质量

# 使用Black格式化代码
black src/ tests/

# 运行类型检查（如果配置了mypy）
mypy src/

# 代码检查（如果配置了flake8）
flake8 src/ tests/

使用

环境变量

MEILI_HTTP_ADDR=http://localhost:7700  # 默认Meilisearch URL
MEILI_MASTER_KEY=your_master_key       # 可选：默认Meilisearch API密钥

动态连接配置

服务器提供了在运行时查看和更新连接设置的工具：

get-connection-settings：查看当前连接URL和API密钥状态
update-connection-settings：更新URL和/或API密钥以连接到不同的Meilisearch实例

通过MCP的示例用法：

// 获取当前设置
{
  "name": "get-connection-settings"
}

// 更新连接设置
{
  "name": "update-connection-settings",
  "arguments": {
    "url": "http://new-host:7700",
    "api_key": "new-api-key"
  }
}

搜索功能

服务器提供了一个灵活的搜索工具，可以在一个或所有索引中搜索：

search：通过Meilisearch索引进行搜索，可选参数

通过MCP的示例用法：

// 在特定索引中搜索
{
  "name": "search",
  "arguments": {
    "query": "搜索词",
    "indexUid": "movies",
    "limit": 10
  }
}

// 在所有索引中搜索
{
  "name": "search",
  "arguments": {
    "query": "搜索词",
    "limit": 5,
    "sort": ["releaseDate:desc"]
  }
}

可用的搜索参数：

query：搜索查询（必需）
indexUid：要搜索的特定索引（可选）
limit：每个索引的最大结果数（可选，默认：20）
offset：要跳过的结果数（可选，默认：0）
filter：过滤表达式（可选）
sort：排序规则（可选）

运行服务器

python -m src.meilisearch_mcp

与Claude Desktop一起使用

要与Claude Desktop一起使用，请将以下内容添加到你的claude_desktop_config.json中：

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

使用MCP Inspector进行测试

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

可用工具

连接管理

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：列出任务，支持可选过滤器：
- limit：要返回的最大任务数
- from：要跳过的任务数
- reverse：任务的排序顺序
- batchUids：按批次UID过滤
- uids：按任务UID过滤
- canceledBy：按取消来源过滤
- types：按任务类型过滤
- statuses：按任务状态过滤
- indexUids：按索引UID过滤
- afterEnqueuedAt/beforeEnqueuedAt：按入队时间过滤
- afterStartedAt/beforeStartedAt：按开始时间过滤
- afterFinishedAt/beforeFinishedAt：按完成时间过滤
cancel-tasks：取消挂起或已入队的任务
delete-tasks：删除已完成的任务

系统监控

health-check：基本健康检查
get-health-status：综合健康状态
get-version：获取Meilisearch版本信息
get-stats：获取数据库统计信息
get-system-info：获取系统级信息

贡献

我们欢迎贡献！请遵循以下指南：

Fork并克隆仓库
设置开发环境，按照上述开发设置部分
从main创建功能分支
先编写测试，如果添加新功能（测试驱动开发）
在提交前本地运行测试，确保所有测试通过
使用Black格式化代码，确保代码质量
提交更改，并附上描述性的提交信息
推送到你的fork并创建拉取请求

开发工作流

# 创建功能分支
git checkout -b feature/你的功能名称

# 进行更改，先编写测试
# 编辑文件...

# 运行测试以确保一切正常
python -m pytest tests/ -v

# 格式化代码
black src/ tests/

# 提交并推送
git add .
git commit -m "添加功能描述"
git push origin feature/你的功能名称

测试指南

所有新功能都应包括测试
在提交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. 从最新的main创建分支
git checkout main
git pull origin main
git checkout -b release/v0.5.0

# 2. 更新pyproject.toml中的版本
# 将version = "0.4.0"行更新为你的新版本

# 3. 提交并推送
git add pyproject.toml
git commit -m "版本升级到0.5.0"
git push origin release/v0.5.0

# 4. 创建PR并获取审核/合并
gh pr create --title "发布v0.5.0" --body "版本升级发布"

3. 合并到Main

一旦PR被批准并合并到main，GitHub Action将自动：

检测版本更改
构建包
发布到PyPI，地址为https://pypi.org/p/meilisearch-mcp
使新版本通过pip install meilisearch-mcp可用

4. 验证发布

合并后，验证发布：

# 检查GitHub Action状态
gh run list --workflow=publish.yml

# 在PyPI上验证（可能需要几分钟）
pip index versions meilisearch-mcp

# 测试新版本的安装
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 .
生产：从PyPI安装，使用pip install meilisearch-mcp
特定版本：使用pip install meilisearch-mcp==0.5.0安装

许可证

MIT