⚙

Meilisearch MCP服务器

Meilisearch MCP服务器是一个模型上下文协议服务器，使任何MCP兼容的客户端（包括Claude、OpenAI代理和其他LLM）能够与Meilisearch交互，通过自然对话管理搜索索引、执行搜索和处理数据。

作者 By meilisearch

本地部署可托管搜索引擎

GitHub

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.️⃣ 安装软件包

BASH``` 1 2 3 4# Using pip pip install meilisearch-mcp

Or using uvx (recommended)

uvx -n meilisearch-mcp


### 2.️⃣ 配置Claude桌面


将此添加到您的 `claude_desktop_config.json`:


JSON```
1
2
3
4
5
6
7
8{
  "mcpServers": {
    "meilisearch": {
      "command": "uvx",
      "args": ["-n", "meilisearch-mcp"]
    }
  }
}

3.️⃣ 启动Meilisearch

BASH``` 1 2 3 4 5# Using Docker (recommended) docker run -d -p 7700:7700 getmeili/meilisearch:v1.28

Or using Homebrew

brew install meilisearch meilisearch


就是这样！现在，您可以让您的AI助手搜索和管理您的Meilisearch数据！ 🎉


## 📚 例子


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

1 2 3 4 5 6You: “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!


### 🔍 高级搜索示例：

1 2 3 4 5You: “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


BASH```
1pip install meilisearch-mcp

来源（用于开发）

BASH``` 1 2 3 4 5 6 7# 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


BASH```
1
2
3
4
5
6
7
8
9# 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

从源代码构建

BASH``` 1 2 3 4 5 6# 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镜像：


YAML```
1
2
3
4
5meilisearch-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

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

🌍 环境变量

配置默认连接设置：

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


## 💻 发展


### 设置开发环境


1. **启动Meilisearch**:


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

安装开发依赖项:

BASH``` 1uv pip install -r requirements-dev.txt

3. **运行测试**:


BASH```
1python -m pytest tests/ -v

格式化代码:

BASH``` 1black src/ tests/



### MCP检验员测试


BASH```
1npx @modelcontextprotocol/inspector python -m src.meilisearch_mcp

🤝 社区与支持

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

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

🤗 贡献

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

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

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

📦 发布过程

此项目使用自动版本控制和发布。当版本在 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：获取系统级信息

开发设置

先决条件

启动Meilisearch服务器:

BASH``` 1 2 3 4 5 6# 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

2. **安装开发工具**:


BASH```
1
2
3
4# 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工具功能的全面集成测试：

BASH``` 1 2 3 4 5 6 7 8# 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`.


### 代码质量


BASH```
1
2
3
4
5
6# 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/

贡献指南

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

开发工作流程

BASH``` 1 2 3 4 5 6 7 8 9 10 11 12# 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上创建新版本
2. **版本检测**：工作流在中比较当前版本 `pyproject.toml` 使用之前的提交来检测更改
3. **PyPI出版**：使用PyPA的官方发布操作进行可信发布（不需要手动API密钥）


#### 创建新版本


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


##### 1.确定版本号


跟随 [语义化版本](https://semver.org/) （主要。次要。补丁）：


- **补丁** （例如，0.4.0→ 0.4.1):Bug修复、文档更新、细微改进
- **次要的** （例如，0.4.0→ 0.5.0):新功能、新MCP工具、重大增强
- **重大** （例如，0.5.0→ 1.0.0):突破性变化，API重大变化


##### 2.更新版本并创建PR


BASH```
1
2
3
4
5
6
7
8
9
10
11
12# 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将自动：

检测版本更改
构建包
发布到PyPIhttps://pypi.org/p/meilisearch-mcp
通过以下方式提供新版本 pip install meilisearch-mcp

4.验证发布

合并后，验证版本：

BASH``` 1 2 3 4 5 6# 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`