金大哥 - easysearch-mcp-server MCP 详情

article

README

🚀 Easysearch MCP 服务器

这是一个 MCP 服务器，可让 AI Agent 操作 INFINI Easysearch（兼容 Elasticsearch/OpenSearch API），为 AI 与搜索服务的交互提供便利。

🚀 快速开始

1. 配置 MCP 客户端

Kiro (.kiro/settings/mcp.json)：

{
  "mcpServers": {
    "easysearch": {
      "command": "python3",
      "args": ["-m", "easysearch_mcp.server"],
      "cwd": "/path/to/easysearch-mcp-server/src",
      "env": {
        "EASYSEARCH_URL": "https://localhost:9200",
        "EASYSEARCH_USER": "admin",
        "EASYSEARCH_PASSWORD": "your-password",
        "PYTHONPATH": "/path/to/easysearch-mcp-server/src"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "easysearch": {
      "command": "python3",
      "args": ["-m", "easysearch_mcp.server"],
      "cwd": "/path/to/easysearch-mcp-server/src",
      "env": {
        "EASYSEARCH_URL": "https://localhost:9200",
        "EASYSEARCH_USER": "admin",
        "EASYSEARCH_PASSWORD": "your-password",
        "PYTHONPATH": "/path/to/easysearch-mcp-server/src"
      }
    }
  }
}

⚠️ 重要提示

将 /path/to/easysearch-mcp-server 替换为实际的项目路径。

2. 开始使用

配置完成后，AI Agent 就可以直接操作 Easysearch 了，例如：

"查看集群健康状态"
"创建一个 products 索引"
"搜索价格大于 100 的商品"
"统计每个分类的订单数量"

✨ 主要特性

🔧 121 个工具：覆盖集群、索引、文档、搜索、监控等全部功能，满足多样化的操作需求。
🔌 即插即用：支持 Kiro、Claude Desktop 等 MCP 客户端，方便集成。
🔒 安全连接：支持 HTTPS 和基础认证，保障数据传输安全。
⚡ 高性能：基于 httpx 异步 HTTP 客户端，提升操作效率。

📦 安装指南

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

# 安装依赖
pip install -e .

💻 使用示例

基础用法

集群监控

查看集群健康状态
→ cluster_health()

查看所有节点
→ cat_nodes()

查看线程池状态
→ cat_thread_pool()

按大小排序查看索引
→ cat_indices(sort_by="store.size", order="desc")

索引操作

创建索引
→ index_create("products", 
    mappings={"properties": {"name": {"type": "text"}, "price": {"type": "float"}}},
    settings={"number_of_shards": 3})

写入文档
→ doc_index("products", {"name": "iPhone", "price": 999})

批量写入
→ doc_bulk_simple("products", [
    {"name": "iPad", "price": 799},
    {"name": "MacBook", "price": 1299}
])

搜索查询

简单搜索
→ search_simple("products", "iPhone")

DSL 搜索
→ search("products", query={
    "bool": {
        "must": [{"match": {"name": "phone"}}],
        "filter": [{"range": {"price": {"lte": 1000}}}]
    }
})

聚合统计
→ aggregate("orders", aggs={
    "by_status": {"terms": {"field": "status"}},
    "avg_amount": {"avg": {"field": "amount"}}
})

SQL 查询
→ sql_query("SELECT * FROM products WHERE price > 500 ORDER BY price DESC")

索引克隆/拆分/收缩

# 克隆索引（需要先设置只读）
→ index_set_readonly("my-index", True)
→ index_clone("my-index", "my-index-clone")
→ index_set_readonly("my-index", False)

# 收缩索引（需要准备）
→ index_prepare_for_shrink("my-index")
→ index_shrink("my-index", "my-index-shrunk", {"index.number_of_shards": 1})

# 滚动索引（需要可写别名）
→ index_create_with_write_alias("logs-000001", "logs")
→ index_rollover("logs", conditions={"max_docs": 1000000})

📚 详细文档

工具列表

集群管理 (8)

| 工具 | 说明 | |------|------| | cluster_health | 集群健康状态 | | cluster_stats | 集群统计信息 | | cluster_state | 集群状态详情 | | cluster_settings | 获取集群设置 | | cluster_update_settings | 更新集群设置 | | cluster_pending_tasks | 待处理任务 | | cluster_allocation_explain | 分片分配解释 | | cluster_reroute | 手动路由分片 |

索引管理 (25)

| 工具 | 说明 | |------|------| | index_create | 创建索引 | | index_delete | 删除索引 | | index_exists | 检查索引是否存在 | | index_get | 获取索引详情 | | index_get_mapping | 获取映射 | | index_put_mapping | 更新映射 | | index_get_settings | 获取设置 | | index_put_settings | 更新设置 | | index_open | 打开索引 | | index_close | 关闭索引 | | index_refresh | 刷新索引 | | index_flush | 刷盘 | | index_forcemerge | 强制合并段 | | index_clear_cache | 清除缓存 | | index_stats | 索引统计 | | index_segments | 段信息 | | index_recovery | 恢复状态 | | index_shard_stores | 分片存储信息 | | index_set_readonly | 设置只读（clone/split/shrink 前置条件）| | index_prepare_for_shrink | 准备收缩（shrink 前置条件）| | index_create_with_write_alias | 创建带可写别名的索引（rollover 前置条件）| | index_clone | 克隆索引 | | index_split | 拆分索引 | | index_shrink | 收缩索引 | | index_rollover | 滚动索引 |

别名管理 (4)

| 工具 | 说明 | |------|------| | alias_get | 获取别名 | | alias_create | 创建别名 | | alias_delete | 删除别名 | | alias_actions | 批量别名操作 |

模板管理 (3)

| 工具 | 说明 | |------|------| | template_get | 获取模板 | | template_create | 创建模板 | | template_delete | 删除模板 |

文档操作 (11)

| 工具 | 说明 | |------|------| | doc_index | 写入文档 | | doc_get | 获取文档 | | doc_exists | 检查文档是否存在 | | doc_delete | 删除文档 | | doc_update | 更新文档 | | doc_bulk | 批量操作 | | doc_bulk_simple | 简化批量写入 | | doc_mget | 批量获取 | | doc_source | 获取文档源 | | doc_delete_by_query | 按查询删除 | | doc_update_by_query | 按查询更新 |

搜索功能 (15)

| 工具 | 说明 | |------|------| | search | DSL 搜索 | | search_simple | 简单关键词搜索 | | search_template | 模板搜索 | | msearch | 多重搜索 | | count | 文档计数 | | validate_query | 验证查询 | | explain | 解释评分 | | aggregate | 聚合查询 | | aggregate_simple | 简化聚合 | | scroll_start | 开始滚动搜索 | | scroll_next | 获取下一批 | | scroll_clear | 清除滚动上下文 | | field_caps | 字段能力 | | knn_search | 向量搜索 | | sql_query | SQL 查询 |

CAT API (19)

| 工具 | 说明 | |------|------| | cat_health | 集群健康 | | cat_nodes | 节点列表 | | cat_indices | 索引列表 | | cat_shards | 分片分布 | | cat_allocation | 磁盘分配 | | cat_thread_pool | 线程池状态 | | cat_master | 主节点信息 | | cat_segments | 段信息 | | cat_count | 文档计数 | | cat_recovery | 恢复状态 | | cat_pending_tasks | 待处理任务 | | cat_aliases | 别名列表 | | cat_templates | 模板列表 | | cat_plugins | 插件列表 | | cat_fielddata | Fielddata 使用 | | cat_nodeattrs | 节点属性 | | cat_repositories | 快照仓库 | | cat_snapshots | 快照列表 | | cat_tasks | 任务列表 |

节点管理 (5)

| 工具 | 说明 | |------|------| | nodes_info | 节点信息 | | nodes_stats | 节点统计 | | nodes_hot_threads | 热点线程 | | nodes_usage | 功能使用统计 | | nodes_reload_secure_settings | 重载安全设置 |

快照管理 (10)

| 工具 | 说明 | |------|------| | snapshot_repo_create | 创建仓库 | | snapshot_repo_get | 获取仓库 | | snapshot_repo_delete | 删除仓库 | | snapshot_repo_verify | 验证仓库 | | snapshot_create | 创建快照 | | snapshot_get | 获取快照 | | snapshot_status | 快照状态 | | snapshot_delete | 删除快照 | | snapshot_restore | 恢复快照 | | snapshot_clone | 克隆快照 |

快照生命周期管理 SLM (6)

| 工具 | 说明 | |------|------| | slm_policy_create | 创建策略 | | slm_policy_get | 获取策略 | | slm_policy_delete | 删除策略 | | slm_policy_explain | 解释策略 | | slm_policy_start | 启动策略 | | slm_policy_stop | 停止策略 |

任务管理 (3)

| 工具 | 说明 | |------|------| | tasks_list | 任务列表 | | tasks_get | 任务详情 | | tasks_cancel | 取消任务 |

Ingest Pipeline (6)

| 工具 | 说明 | |------|------| | pipeline_get | 获取 Pipeline | | pipeline_create | 创建 Pipeline | | pipeline_delete | 删除 Pipeline | | pipeline_simulate | 模拟 Pipeline | | ingest_stats | Ingest 统计 | | ingest_processor_grok | Grok 模式列表 |

ILM 索引生命周期管理 (5)

| 工具 | 说明 | |------|------| | ilm_policy_get | 获取 ILM 策略 | | ilm_policy_create | 创建 ILM 策略 | | ilm_policy_delete | 删除 ILM 策略 | | ilm_add_policy | 给索引绑定 ILM 策略 | | ilm_remove_policy | 从索引移除 ILM 策略 |

其他 (1)

| 工具 | 说明 | |------|------| | reindex | 重建索引 |

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | EASYSEARCH_URL | Easysearch 地址 | https://localhost:9200 | | EASYSEARCH_USER | 用户名 | admin | | EASYSEARCH_PASSWORD | 密码 | - |

开发

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

# 安装依赖
pip install -e .

# 运行测试
pytest

# 代码格式化
black src/
ruff check src/

兼容性测试

所有 121 个工具已在 INFINI Easysearch 上完成测试验证： | 分类 | 工具数 | 状态 | |------|--------|------| | 集群管理 | 8 | ✅ 全部通过 | | 索引管理 | 25 | ✅ 全部通过 | | 别名管理 | 4 | ✅ 全部通过 | | 模板管理 | 3 | ✅ 全部通过 | | 文档操作 | 11 | ✅ 全部通过 | | 搜索功能 | 15 | ✅ 全部通过 | | CAT API | 19 | ✅ 全部通过 | | 节点管理 | 5 | ✅ 全部通过 | | 快照管理 | 10 | ✅ 全部通过 | | SLM | 6 | ✅ 全部通过 | | 任务管理 | 3 | ✅ 全部通过 | | Ingest Pipeline | 6 | ✅ 全部通过 | | ILM | 5 | ✅ 全部通过 | | 其他 | 1 | ✅ 全部通过 |

⚠️ 重要提示

快照和 SLM 功能需要服务器配置 path.repo 才能创建仓库。

📄 许可证

MIT License

easysearch-mcp-server