STARWARCLOUD STARWAR.AI
返回市场
美力搜索-mcp

美力搜索-mcp

作者：meilisearch141 星标更新：2025-08-28
安装使用来源：spider==github.com

项目介绍

<div align="center"> <img src="https://github.com/meilisearch/meilisearch/blob/main/assets/logo.svg" alt="Meilisearch" width="200" height="200" /> </div> <h1 align="center">Meilisearch MCP 服务器</h1> <h4 align="center"> <a href="https://github.com/meilisearch/meilisearch">Meilisearch</a> | <a href="https://www.meilisearch.com/cloud?utm_campaign=oss&utm_source=github&utm_medium=meilisearch-mcp">Meilisearch Cloud</a> | <a href="https://www.meilisearch.com/docs">文档</a> | <a href="https://discord.meilisearch.com">Discord</a> </h4> <p align="center"> <a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/v/meilisearch-mcp.svg" alt="PyPI 版本"></a> <a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/pyversions/meilisearch-mcp.svg" alt="Python 版本"></a> <a href="https://github.com/meilisearch/meilisearch-mcp/actions"><img src="https://github.com/meilisearch/meilisearch-mcp/workflows/Test%20and%20Lint/badge.svg" alt="测试"></a> <a href="https://github.com/meilisearch/meilisearch-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-informational" alt="许可证"></a> <a href="https://pypi.org/project/meilisearch-mcp/"><img src="https://img.shields.io/pypi/dm/meilisearch-mcp" alt="下载量"></a> </p> <p align="center">⚡ 将任何LLM连接到Meilisearch，并通过闪电般快速的搜索能力增强您的AI！ 🔍</p>

🤔 这是什么？

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

为什么使用这个？

  • 🤖 通用兼容性 - 适用于任何MCP客户端，而不仅仅是Claude
  • 🗣️ 自然语言控制 - 通过与任何LLM的对话来管理Meilisearch
  • 🚀 零学习曲线 - 不需要学习Meilisearch的API
  • 🔧 全功能访问 - 所有Meilisearch的功能都在您手中
  • 🔄 动态连接 - 在不同Meilisearch实例之间切换
  • 📡 标准I/O传输 - 目前使用标准I/O；原生Meilisearch MCP支持即将推出！

✨ 关键特性

  • 📊 索引和文档管理 - 创建、更新和管理搜索索引
  • 🔍 智能搜索 - 跨单个或多个索引进行高级过滤搜索
  • ⚙️ 设置配置 - 微调搜索相关性和性能
  • 📈 任务监控 - 跟踪索引进度和系统操作
  • 🔐 API密钥管理 - 安全访问控制
  • 🏥 健康监控 - 监控您的Meilisearch实例
  • 🐍 Python实现 - 也有TypeScript版本

🚀 快速开始

只需三步即可启动！

1️⃣ 安装包

# 使用pip
pip install meilisearch-mcp

# 或者使用uvx（推荐）
uvx -n meilisearch-mcp

2️⃣ 配置Claude Desktop

在您的claude_desktop_config.json中添加以下内容：

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

3️⃣ 启动Meilisearch

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

# 或者使用Homebrew
brew install meilisearch
meilisearch

就这样！现在您可以询问您的AI助手来搜索和管理您的Meilisearch数据了！ 🎉

📚 示例

💬 自然地与您的AI助手交谈：

您：创建一个名为“产品”的新索引，以“id”作为主键
AI：我将为您创建该索引... ✓ 索引“产品”已成功创建！

您：向索引中添加一些产品
AI：我将添加这些产品... ✓ 已向“产品”索引添加了5个文档

您：搜索价格低于$50且类别中有“电子产品”的产品
AI：我将搜索这些产品... 找到了12个匹配的产品！

🔍 高级搜索示例：

您：跨我的所有索引搜索“机器学习”，按日期排序
AI：正在跨所有索引搜索... 从3个索引中找到了47个结果：
- '博客文章'：23篇关于ML的文章
- '文档'：15篇技术指南
- '教程'：9篇动手教程

🔧 安装

先决条件

  • Python ≥ 3.9
  • 运行中的Meilisearch实例
  • 兼容MCP的客户端（Claude Desktop、OpenAI代理等）

从PyPI安装

pip install meilisearch-mcp

从源码安装（用于开发）

# 克隆仓库
git clone https://github.com/meilisearch/meilisearch-mcp.git
cd meilisearch-mcp

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

使用Docker

非常适合容器化环境，如n8n工作流！

从Docker Hub拉取

# 拉取最新镜像
docker pull getmeili/meilisearch-mcp:latest

# 或特定版本
docker pull getmeili/meilisearch-mcp:0.5.0

# 运行容器
docker run -it \
  -e MEILI_HTTP_ADDR=http://your-meilisearch:7700 \
  -e MEILI_MASTER_KEY=your-master-key \
  getmeili/meilisearch-mcp:latest

从源码构建

# 构建自己的镜像
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

🛠️ 您可以做什么？

<details> <summary><b>🔗 连接管理</b></summary>
  • 查看当前连接设置
  • 动态切换Meilisearch实例
  • 实时更新API密钥
</details> <details> <summary><b>📁 索引操作</b></summary>
  • 使用自定义主键创建新索引
  • 列出所有索引及其统计信息
  • 删除索引及其数据
  • 获取详细的索引指标
</details> <details> <summary><b>📄 文档管理</b></summary>
  • 添加或更新文档
  • 分页检索文档
  • 批量导入数据
</details> <details> <summary><b>🔍 搜索能力</b></summary>
  • 带有过滤器、排序和分面的搜索
  • 多索引搜索
  • 带有向量的语义搜索
  • 混合搜索（关键词+语义）
</details> <details> <summary><b>⚙️ 设置与配置</b></summary>
  • 配置排名规则
  • 设置分面和过滤
  • 管理可搜索属性
  • 自定义拼写容错
</details> <details> <summary><b>🔐 安全性</b></summary>
  • 创建和管理API密钥
  • 设置细粒度权限
  • 监控密钥使用情况

⚠️ 注意：虽然可以在聊天中直接添加和更新主机和API密钥以方便使用，但这种方法主要是为了开发用途（例如，实时连接到多个实例）。它不遵循最佳MCP安全实践，在没有适当防护的情况下不应在生产环境中使用。

</details> <details> <summary><b>📊 监控与健康</b></summary>
  • 健康检查
  • 系统统计信息
  • 任务监控
  • 版本信息
</details>

🌍 环境变量

配置默认连接设置：

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

💻 开发

设置开发环境

  1. 启动Meilisearch：

    docker run -d -p 7700:7700 getmeili/meilisearch:v1.6

  2. 安装开发依赖项：

    uv pip install -r requirements-dev.txt

  3. 运行测试：

    python -m pytest tests/ -v

  4. 格式化代码：

    black src/ tests/

使用MCP Inspector进行测试

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 社区和支持

我们很乐意听到您的声音！以下是获取帮助和联系的方式：

🤗 贡献

我们欢迎贡献！这里是开始的方法：

  1. 分叉仓库
  2. 创建功能分支（git checkout -b feature/amazing-feature）
  3. 为您的更改编写测试
  4. 进行更改并运行测试
  5. 使用black格式化代码
  6. 提交更改（git commit -m '添加精彩功能'）
  7. 推送到您的分支（git push origin feature/amazing-feature）
  8. 打开Pull Request

详见贡献指南以获取更多详情。

📦 发布流程

此项目使用自动版本管理和发布。当main分支上的pyproject.toml中的版本号发生变化时，包会自动发布到PyPI。

详见发布流程部分以获取详细说明。

📄 许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。

<p align="center"> <b>Meilisearch</b> 是一个开源搜索引擎，提供愉悦的搜索体验。<br> 了解更多关于Meilisearch的信息，请访问 <a href="https://www.meilisearch.com">meilisearch.com</a> </p>
<details> <summary><h2>📖 完整文档</h2></summary>

可用工具

连接管理

  • 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：获取系统级别信息

开发设置

先决条件

  1. 启动Meilisearch服务器：

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

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

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

  2. 安装开发工具：

    # 安装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实例。

代码质量

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

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

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

贡献指南

  1. 分叉并克隆仓库
  2. 按照上述开发设置部分设置开发环境
  3. 从main创建功能分支
  4. 首先编写测试（如果添加新功能，采用测试驱动开发）
  5. 本地运行测试，确保所有测试通过后再提交
  6. 使用Black格式化代码并确保代码质量
  7. 提交更改，附带描述性的提交消息
  8. 推送到您的分叉并创建pull request

开发工作流程

# 创建功能分支
git checkout -b feature/your-feature-name

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

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

# 格式化代码
black src/ tests/

# 提交和推送
git add .
git commit -m "添加功能描述"
git push origin feature/your-feature-name

测试指南

  • 所有新功能应包括测试
  • 提交PR之前测试应全部通过
  • 使用描述性测试名称和清晰的断言
  • 测试成功和错误案例
  • 运行测试前确保Meilisearch正在运行

发布流程

此项目使用自动版本管理和发布到PyPI。发布流程设计为简单且自动化。

发布如何工作

  1. 自动发布：当main分支上的pyproject.toml中的版本号发生变化时，GitHub Action会自动：

    • 构建Python包
    • 使用可信发布将其发布到PyPI
    • 在GitHub上创建新版本

  2. 版本检测：工作流比较pyproject.toml中的当前版本与前一提交以检测变化

  3. PyPI发布：使用PyPA官方发布的动作，使用可信发布（无需手动API密钥）

创建新版本

要创建新版本，请遵循以下步骤：

1. 确定版本号

遵循语义化版本控制（MAJOR.MINOR.PATCH）：

  • PATCH（例如，0.4.0 → 0.4.1）：修复错误，更新文档，小改进
  • MINOR（例如，0.4.0 → 0.5.0