Meilisearch MCP Server

Meilisearch MCP Server

Meilisearch | Meilisearch Cloud | Documentation | Discord

⚡ Connect any LLM to Meilisearch and supercharge your AI with lightning-fast search capabilities! 🔍

🤔 这是什么？

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

为什么要用这个？

• 🤖 通用兼容性 -适用于任何MCP客户端，而不仅仅是Claude
• 🗣️ 自然语言控制 -通过与任何法学硕士的对话来管理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桌面

将此添加到您的 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

🛠️ 你能做什么？

🔗 Connection Management

• 查看当前连接设置
• 动态切换Meilisearch实例
• 动态更新API密钥

📁 Index Operations

• 使用自定义主键创建新索引
• 列出所有带有统计数据的指数
• 删除索引及其数据
• 获取详细的指标

📄 Document Management

• 添加或更新文档
• 使用分页检索文档
• 批量导入数据

🔍 Search Capabilities

• 使用过滤器、排序和方面进行搜索
• 多索引搜索
• 基于向量的语义搜索
• 混合搜索（关键字+语义）

⚙️ Settings & Configuration

• 配置排名规则
• 设置分面和过滤
• 管理可搜索属性
• 自定义拼写错误容忍度

🔐 Security

• 创建和管理API密钥
• 设置细粒度权限
• 监控密钥使用情况

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

📊 Monitoring & Health

• 健康检查
• 系统统计信息
• 任务监控
• 版本信息

🌍 环境变量

配置默认连接设置：

MEILI_HTTP_ADDR=http://localhost:7700  # Default Meilisearch URL
MEILI_MASTER_KEY=your_master_key       # Optional: Default API key

💻 发展

设置开发环境

1. 启动Meilisearch:

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

1. 安装开发依赖项:

   uv pip install -r requirements-dev.txt

1. 运行测试:

   python -m pytest tests/ -v

1. 格式化代码:

   black src/ tests/

MCP检验员测试

npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 社区与支持

我们很乐意收到您的来信！以下是如何获得帮助和连接：

• 💬 加入我们的Discord -与社区聊天
• 🐛 报告问题 -发现bug了吗？让我们知道！
• 💡 功能请求 -有主意吗？我们在听！
• 📖 Meilisearch文档 -了解更多关于Meilisearch的信息

🤗 贡献

我们欢迎捐款！以下是如何开始：

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 为您的更改编写测试
4. 进行更改并运行测试
5. 使用格式化代码 black
6. 提交您的更改(git commit -m 'Add amazing feature')
7. 推到您的分支(git push origin feature/amazing-feature)
8. 打开拉取请求

查看我们的 贡献指南 了解更多详情。

📦 发布过程

此项目使用自动版本控制和发布。当版本在 pyproject.toml 更改关于 main 分支，包会自动发布到PyPI。

看 发布过程 详细说明部分。

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

Meilisearch is an open-source search engine that offers a delightful search experience.

Learn more about Meilisearch at meilisearch.com

______________________________________________________________________

📖 Full Documentation

可用工具

连接管理

• get-connection-settings：查看当前美丽搜索连接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服务器:

   # 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

1. 安装开发工具:

   # 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/

重要：测试需要在上运行Meilisearch实例 http://localhost:7700.

代码质量

# 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/

贡献指南

1. 分叉和克隆 存储库
2. 设置开发环境 遵循上面的“开发设置”部分
3. 创建要素分支 从 main
4. 先写测试 如果添加新功能（测试驱动开发）
5. 在本地运行测试 确保在提交之前通过所有测试
6. 格式化代码 黑色，确保代码质量
7. 提交更改 带有描述性提交消息
8. 推你的叉子 并创建一个pull请求

开发工作流程

# 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。发布过程被设计为简单和自动化。

发布工作原理

1. 自动发布：当版本号在 pyproject.toml 更改关于 main 分支，GitHub操作自动执行：

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

1. 版本检测：工作流在中比较当前版本 pyproject.toml 使用之前的提交来检测更改

1. PyPI出版：使用PyPA的官方发布操作进行可信发布（不需要手动API密钥）

创建新版本

要创建新版本，请执行以下步骤：

1.确定版本号

跟随 语义化版本 （主要。次要。补丁）：

• 补丁 （例如，0.4.0→ 0.4.1):Bug修复、文档更新、细微改进
• 次要的 （例如，0.4.0→ 0.5.0):新功能、新MCP工具、重大增强
• 重大 （例如，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.合并到主

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

1. 检测版本更改
2. 构建包
3. 发布到PyPIhttps://pypi.org/p/meilisearch-mcp
4. 通过以下方式提供新版本 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操作日志中的Python包构建错误

PyPI发布失败：验证包名称以及是否正确配置了受信任的发布

版本冲突：确保新版本号以前未在PyPI上使用过

开发版本与生产版本

• 发展：使用从源代码安装 pip install -e .
• 生产：使用从PyPI安装 pip install meilisearch-mcp
• 具体版本：使用安装 pip install meilisearch-mcp==0.5.0