基于MCP协议实现自然语言查询Elasticsearch：Gemini CLI扩展实战

1. 项目概述与核心价值

最近在折腾AI Agent和LLM应用开发，发现一个痛点：如何让大语言模型（比如Gemini）直接、安全地访问和操作我们存储在Elasticsearch里的海量数据？无论是日志分析、用户行为查询，还是业务指标聚合，手动写DSL查询或者临时写脚本都太慢了。正好，Elastic官方推出了一个实验性的项目——gemini-cli-elasticsearch，它作为Gemini CLI的一个扩展，通过Model Context Protocol（MCP）和Agent Skills，为开发者提供了一个用自然语言与Elasticsearch对话的桥梁。

简单来说，这个扩展让你能在终端里，直接用像“帮我查一下上周所有报错的日志”这样的自然语言，让Gemini CLI去调用Elasticsearch的工具，执行搜索、获取映射、运行ES|QL查询等操作，并把结果清晰地返回给你。这不仅仅是把查询语句从键盘敲击变成了语音输入，其核心价值在于将复杂的搜索语法和数据结构理解能力“外包”给了AI，极大地提升了数据探索和原型验证的效率。对于开发者、运维工程师和数据分析师来说，这相当于多了一个精通Elasticsearch的AI助手，尤其适合在需要快速验证数据假设、排查问题或者构建AI Agent工作流的场景下使用。

2. 核心原理与架构解析

2.1 Model Context Protocol（MCP）的角色

MCP是这套方案的核心通信协议。你可以把它理解为一个标准化的“插件接口”或“工具调用规范”。gemini-cli-elasticsearch扩展本身并不直接包含搜索逻辑，它的主要职责是作为一个客户端，去连接一个实现了MCP协议的服务器——也就是Elastic Agent Builder MCP Server。

这个MCP Server运行在你的Elasticsearch集群端（Elastic Serverless或8.13+/9.3+版本支持），它封装了对Elasticsearch集群的安全访问能力，并对外暴露出一系列定义好的“工具”（Tools），比如platform_core.search、platform_core.list_indices等。当你在Gemini CLI中输入一个自然语言查询时，CLI会先将你的意图发送给Gemini模型进行分析，模型识别出需要调用Elasticsearch工具后，就会通过MCP协议，指挥这个扩展去调用对应的工具。工具执行完毕后，结果再通过MCP协议返回给CLI并呈现给你。

这种架构的优势非常明显：

1. 安全性：你的API Key和集群访问凭证只存在于你的本地环境变量和远端的MCP Server配置中，不会泄露给第三方AI模型。模型只知道“调用某个工具”，而不知道具体的连接细节。
2. 能力标准化：MCP定义了一套清晰的工具接口，使得不同的AI前端（如Gemini CLI、其他兼容MCP的客户端）都能以同样的方式使用Elasticsearch的能力。
3. 灵活性：Elastic可以在服务器端更新和增加新的工具，而客户端扩展可能只需要极少的改动或无需改动即可获得新能力。

2.2 Agent Skills 的补充作用

如果说MCP提供了基础的、标准化的工具调用能力，那么Agent Skills则提供了更高级、更场景化的“技能包”。Skills是用JavaScript编写的，它们可以组合多个基础工具调用，加入更复杂的逻辑，甚至与Kibana、Observability等其他Elastic Stack组件交互。

在0.3.0版本之后，Skills被独立到了一个叫elastic/agent-skills的仓库中。你可以通过运行附带的skills.js脚本，以交互式的方式选择安装你需要的技能。例如，一个“分析错误趋势”的技能，内部可能会先调用list_indices找到日志索引，再调用search进行聚合查询，最后将结果格式化为更易读的报告。这对于构建复杂的自动化Agent工作流至关重要。

2.3 扩展、MCP Server与Elasticsearch的协作流程

整个数据流的协作可以概括为以下几步：

1. 用户发起请求：你在终端输入gemini chat “列出所有索引”。
2. 意图识别与工具匹配：Gemini CLI将问题发送给Gemini模型。模型理解到这是一个需要列举Elasticsearch资源的请求，于是决定调用platform_core.list_indices这个工具。
3. MCP协议调用：Gemini CLI通过已安装的elasticsearch扩展，按照MCP格式封装一个工具调用请求，发送到你配置的ELASTIC_MCP_URL对应的服务器。
4. 服务器执行与安全校验：Elastic Agent Builder MCP Server收到请求，使用你提供的ELASTIC_API_KEY进行身份验证和权限校验。验证通过后，它在内部调用Elasticsearch的REST API执行GET /_cat/indices或类似的操作。
5. 结果返回与呈现：MCP Server获取到索引列表数据，将其格式化为MCP响应，通过原路返回给Gemini CLI。CLI再将这个结构化的结果以清晰的文本表格形式输出到你的终端。

3. 环境准备与详细安装指南

3.1 前置条件检查

在开始安装扩展之前，请确保你的环境满足以下要求，这能避免很多后续问题：

1. Gemini CLI：你需要在本地正确安装并配置好Google的Gemini CLI工具。可以访问其GitHub仓库查看安装方法。确保gemini命令在终端中可用。
2. Elasticsearch 集群：你需要一个正在运行的Elasticsearch集群，并且版本需要支持Elastic Agent Builder功能。根据官方文档，这通常要求是Elasticsearch Serverless，或者版本在8.13、9.3及以上。你可以通过Kibana或直接访问{ELASTIC_URL}/来确认集群状态和版本。
3. API Key 权限：你准备的API Key需要具备足够的权限。至少需要包含monitor权限（用于列出索引）和对目标数据索引的read权限。为了安全起见，建议遵循最小权限原则，在Kibana的Stack Management > Security > API Keys中创建时，只授予必要的索引权限。

3.2 分步安装与配置流程

安装过程看似步骤不少，但每一步都有其明确目的。我们一步步来，并解释每个环节的作用。

第一步：安装扩展直接在终端运行安装命令。这个命令会从GitHub仓库拉取扩展并安装到Gemini CLI的扩展目录下（通常是~/.gemini/extensions/）。

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

安装完成后，可以运行gemini extensions list来确认elasticsearch扩展是否在列表中且状态为active。

第二步：获取MCP服务器URL这是连接的关键。你需要进入你的Kibana界面。

1. 导航到Management > Integrations > Agent Builder。
2. 在Agent Builder页面，找到Tools部分，点击Manage MCP。
3. 你会看到一个Copy MCP Server URL的按钮，点击复制。这个URL的格式类似于https://your-deployment.kb.europe-west1.gcp.cloud.es.io/api/agent_builder/mcp。请妥善保存。

注意：如果你在Kibana中找不到Agent Builder或Manage MCP的选项，很可能是因为你的集群版本不支持，或者该功能未被启用。请检查你的Elasticsearch版本并确认已启用相关试用功能。

第三步：创建并获取API Key如果你不是使用start-local这样的本地开发套件（它会自动生成API Key并放在.env文件里），你就需要手动创建一个。

1. 在Kibana中，进入Stack Management > Security > API Keys。
2. 点击Create API key。
3. 为你的密钥起一个名字，例如gemini-cli-access。
4. 在权限部分，我建议创建一个自定义角色会更安全。但为了快速开始，你可以暂时授予一个内置的viewer角色，它通常具备只读权限。在生产环境中，请务必根据实际需要配置精细的索引权限。
5. 创建后，务必立即复制弹出的“编码后的API密钥”。这个字符串只会显示一次，形如a2V5LWlkOmFwaS1rZXktaWQ=。如果你丢失了，只能重新创建。

第四步：设置环境变量环境变量是安全存储配置信息的标准方式。在你的终端中执行以下命令，将尖括号内的占位符替换为你的实际信息。

export ELASTIC_URL="https://your-cluster-host:9200" # 你的Elasticsearch REST API地址 export ELASTIC_MCP_URL="https://your-deployment.../api/agent_builder/mcp" # 第二步复制的URL export ELASTIC_API_KEY="a2V5LWlkOmFwaS1rZXktaWQ=" # 第三步复制的编码API Key

为了让这些配置在每次打开新终端时都生效，你需要将它们添加到你的shell配置文件中。

• Bash用户：echo 'export ELASTIC_URL="..."' >> ~/.bashrc && echo 'export ELASTIC_MCP_URL="..."' >> ~/.bashrc && echo 'export ELASTIC_API_KEY="..."' >> ~/.bashrc
• Zsh用户：将~/.bashrc替换为~/.zshrc。
• Fish Shell用户：set -Ux ELASTIC_URL "..."(注意Fish的语法不同)。

添加后，执行source ~/.bashrc（或对应文件）使配置立即生效，或者直接关闭终端重新打开一个。

第五步：验证连接这是检验前面所有步骤是否正确的关键时刻。

1. 运行gemini mcp list。你期望看到的输出中应该包含一行关于elastic-agent-builder的记录，并且状态是✓ Connected。如果显示Disconnected，请跳转到下面的故障排查部分。
2. 进行一个简单的测试查询：gemini chat “列出我的elasticsearch索引”。如果一切正常，你应该能看到一个格式清晰的索引列表被打印出来。

4. 核心功能使用与实战示例

4.1 基础工具的自然语言调用

安装并连接成功后，你就可以开始用自然语言与你的数据对话了。Gemini模型会尝试理解你的意图，并自动选择最合适的MCP工具。下面是一些典型场景的示例和背后的原理。

场景一：探索数据概貌当你接手一个新集群或想快速了解数据分布时，可以这样问：

gemini chat “我有哪些索引？分别有多少文档？”

模型可能会调用platform_core.list_indices来获取索引列表，甚至可能结合platform_core.search对每个索引做一个_count操作来统计文档数。返回的结果通常会以表格形式呈现，包括索引名、文档数、存储大小和健康状态。

场景二：执行特定搜索假设你有一个名为app-logs-2024.05的日志索引，你想查找错误。

gemini chat “在 app-logs-2024.05 索引里搜索 level 字段为 ERROR 的日志，返回最近10条，并显示 timestamp 和 message 字段”

模型会理解到这是一个针对特定索引的、带过滤条件和字段投影的查询。它会生成一个Elasticsearch DSL查询（使用platform_core.search工具），类似于：

{ "query": { "term": { "level": "ERROR" } }, "sort": [ { "timestamp": { "order": "desc" } } ], "_source": ["timestamp", "message"], "size": 10 }

然后通过MCP执行并返回结果。这种方式让你完全摆脱了手写JSON查询语的繁琐。

场景三：分析数据聚合对于数据分析，聚合查询非常强大。

gemini chat “统计过去24小时内，按小时分组的HTTP状态码为5xx的错误数量”

这个查询更复杂，它包含了时间范围过滤（过去24小时）、桶聚合（按小时）和指标聚合（计数）。模型需要将其转换为一个包含range过滤、date_histogram和terms聚合的DSL。虽然挑战更大，但对于训练有素的模型来说是可以完成的。如果一次查询结果不理想，你可以尝试分步引导，例如先问“查看日志索引中有哪些字段”，再基于字段信息进行更精确的聚合查询。

4.2 直接使用扩展命令

除了依赖模型的自动工具调用，扩展也提供了一些直接的命令（Commands），让你可以更精确地控制操作。在Gemini CLI的聊天界面中，输入/可以看到命令提示。

• /elastic:list-indices：直接调用list_indices工具，快速获取列表。这是最可靠、最快捷的获取索引信息的方式。
• /elastic:explore-indices “logs”：当你只记得索引名的一部分时，这个命令非常有用。它会调用index_explorer工具，进行模糊匹配，找出所有包含“logs”关键词的索引、别名或数据流。
• /elastic:get-mapping my-index：获取指定索引的映射（Mapping）。在编写复杂查询前，了解字段类型（是text还是keyword？有没有嵌套对象？）至关重要。这个命令能帮你快速看清数据结构。
• /elastic:search-dsl：这个命令会进入一个交互模式，引导你或允许你直接输入一个完整的Elasticsearch DSL查询JSON。它跳过了自然语言转换，适合已经明确知道查询语法的场景。
• /elastic:search-esql：同样进入交互模式，用于执行ES|QL查询。ES|QL是Elasticsearch新的管道查询语言，对于熟悉SQL的用户来说更直观。例如，你可以输入FROM app-logs | WHERE level == “ERROR” | STATS count = COUNT(*) by host.name。

4.3 利用ES|QL进行高级分析

ES|QL是Elasticsearch推出的用于数据探索的查询语言，其管道式语法非常适合多步数据处理。通过platform_core.execute_esql工具或/elastic:search-esql命令，你可以发挥其强大威力。

示例：复杂日志分析假设你想分析Nginx访问日志，计算每个接口端点（request.path）的平均响应时间（response.time）和95分位数，并过滤出平均响应时间超过500毫秒的端点。 用自然语言描述可能是：“分析 nginx-access 索引，按请求路径分组，计算平均响应时间和95分位响应时间，只显示平均响应时间大于500ms的。” 模型可能会生成如下ES|QL：

FROM nginx-access-* | WHERE `@timestamp` >= NOW() - 7 DAYS | STATS avg_time = AVG(response.time), p95_time = PERCENTILE(response.time, 95) BY request.path | WHERE avg_time > 500 | SORT avg_time DESC

这个查询清晰地展示了ES|QL的管道流程：从数据源过滤、聚合计算、二次过滤到排序输出。通过自然语言驱动这样的查询，数据分析的门槛被极大地降低了。

5. Agent Skills的安装与应用

5.1 为何需要独立安装Skills

在0.3.0版本之前，Skills可能作为扩展的一部分捆绑安装。现在独立出来，带来了几个好处：

1. 模块化：用户可以根据需要选择安装，减少扩展本身的体积和复杂度。
2. 独立更新：Skills可以独立于主扩展进行迭代和更新，修复bug或增加新功能更快。
3. 生态发展：独立的仓库鼓励社区贡献更多针对特定场景（如安全分析、业务监控）的Skills。

5.2 交互式安装流程

安装Skills的脚本已经随扩展一同安装。你需要在终端中运行以下命令：

node ~/.gemini/extensions/elasticsearch/skills.js --install --interactive

如果你已经在Gemini CLI的聊天界面中，需要加上!前缀来执行shell命令：

!node ~/.gemini/extensions/elasticsearch/skills.js --install --interactive

运行后，脚本会列出elastic/agent-skills仓库中所有可用的技能包。通常包括：

• Elasticsearch Skills：针对ES的增强技能，如更智能的索引分析、数据采样等。
• Kibana Skills：可能与Kibana仪表板、可视化图表交互的技能。
• Observability Skills：针对APM、Metrics、Logs的运维分析技能。
• Security Skills：与Elastic Security相关的检测、调查技能。

脚本会以交互式菜单让你用空格键选择需要安装的技能，然后回车确认。安装过程可能会从GitHub下载代码到本地。

5.3 Skills与MCP Tools的协作与冲突处理

Skills和MCP Tools都能操作Elasticsearch，因此可能存在功能重叠。例如，可能同时存在一个MCP Toolplatform_core.search和一个Skilladvanced_search。

协作：Skills可以看作是更高阶的封装。一个Skill内部可以按顺序调用多个基础的MCP Tools，并加入额外的逻辑处理。例如，一个“生成每周报告”的Skill，可能会先调用list_indices找到正确的索引，再调用search进行聚合，最后将结果格式化为Markdown或HTML。

冲突：当模型面对一个查询时，它可能会困惑于该调用基础的MCP Tool还是更高级的Skill。这可能导致不可预测的行为或错误。

解决方案：官方提供了管理命令。如果你发现Skills和MCP Tools冲突，或者你只想使用Skills，可以禁用MCP Server连接。 在Gemini CLI中输入：

/mcp disable elastic-agent-builder

这样就会断开与MCP Server的连接，模型将只能使用已安装的本地Skills。如果需要恢复MCP连接，使用/mcp enable elastic-agent-builder即可。这给了你根据工作流需求灵活切换底层执行引擎的能力。

6. 常见问题与深度排查指南

即使按照指南操作，也可能会遇到问题。这里整理了一些常见故障及其排查思路，帮你快速定位。

6.1 连接类问题

问题：gemini mcp list显示Disconnected或连接失败。这是最常见的问题，根源在于MCP Server的连通性或认证。

1. 检查环境变量：这是第一步。在终端执行echo $ELASTIC_MCP_URL和echo $ELASTIC_API_KEY，确认输出正确且非空。特别是API Key，确保复制的是完整的、编码后的字符串，没有多余空格或换行。一个快速验证方法是echo -n “你的API Key” | wc -c，看看长度是否合理。
2. 环境变量生效：如果你是在当前终端窗口设置的export，那么它只在本窗口生效。如果你修改了~/.bashrc等文件，需要source该文件或重新打开一个全新的终端窗口。这是最容易忽略的一点。
3. 验证网络与URL：尝试用curl命令测试MCP Server URL是否可达（注意，直接curl可能会返回405 Method Not Allowed，因为需要特定的MCP协议，但至少可以测试网络和基础URL是否正确）。

   curl -v -X OPTIONS “$ELASTIC_MCP_URL”

   如果遇到证书问题（自签名或内部CA），你可能需要设置export NODE_TLS_REJECT_UNAUTHORIZED=0（仅限测试环境，生产环境极其危险）或配置系统信任该CA证书。
4. 检查Elasticsearch集群状态与版本：登录Kibana，检查集群健康状态是否为绿色。并确认你的集群版本是否支持Agent Builder MCP功能（Serverless或 >= 8.13/9.3）。
5. 确认API Key权限与状态：回到Kibana的API Keys页面，检查你使用的Key是否仍然有效（未过期、未禁用）。尝试用这个API Key通过curl直接访问Elasticsearch的REST API，验证其基础权限。

   curl -H “Authorization: ApiKey $ELASTIC_API_KEY” “$ELASTIC_URL/”

   应该能返回集群的基本信息。

6.2 查询执行类问题

问题：模型无法理解我的查询意图，或生成的查询语法错误。自然语言转查询（NL2Query）并非100%准确，其效果取决于描述的清晰度和数据的复杂度。

1. 提供更明确的上下文：在查询中明确指出索引名、字段名。例如，用“在order-*索引中”代替“在我的订单数据中”。如果字段名包含特殊字符或是关键字，使用反引号引用，如`@timestamp`。
2. 分步引导：对于复杂查询，不要试图一步到位。可以先让模型“查看my-index索引的映射”，了解字段结构后，再基于具体字段进行查询。
3. 使用直接命令：如果自然语言转换不理想，直接使用/elastic:search-dsl或/elastic:search-esql命令，手动输入或引导输入精确的查询语句。
4. 检查返回的错误信息：当工具调用失败时，Gemini CLI通常会返回来自Elasticsearch的错误信息。仔细阅读这些信息，例如“index_not_found_exception”意味着索引名写错了，“search_phase_execution_exception”可能意味着查询DSL语法有误。根据错误信息调整你的问题描述。

6.3 性能与结果类问题

问题：查询速度慢，或者返回的结果不是我想要的。这通常与查询本身和数据规模有关。

1. 限制查询范围：在自然语言请求中主动加入时间范围或数据量限制。例如，“搜索今天error.log索引中最近1000条包含‘Timeout’的日志”，就比单纯搜索“包含Timeout的日志”要好得多。模型生成的查询会包含size和range过滤，避免全表扫描。
2. 关注索引模式：如果你的索引是按时间滚动的（如logs-2024.05.01），在查询时使用索引模式logs-*或logs-2024.05*可以让Elasticsearch搜索更少的分片，提升速度。在自然语言中可以说“在logs-2024.05*索引模式中搜索”。
3. 结果格式化：默认返回的可能是原始JSON或简化表格。如果你需要更特定的格式，可以在查询中说明，例如“将结果以JSON格式返回，并包含_id和_score字段”。虽然模型不一定总能完美执行，但这是一个改进方向。

6.4 Skills相关故障

问题：skills.js脚本执行失败或安装Skills后不生效。

1. Node.js环境：确保你的系统安装了Node.js，并且版本不是太旧。运行node --version检查。
2. 脚本路径：确认~/.gemini/extensions/elasticsearch/目录下确实存在skills.js文件。
3. 网络问题：安装Skills需要从GitHub拉取代码，确保你的网络可以访问https://github.com。
4. Skills加载：安装成功后，可能需要重启Gemini CLI会话，或者通过特定的命令（如/skills reload，如果存在）来加载新技能。请参考agent-skills仓库的详细文档。

7. 安全最佳实践与生产环境考量

这个扩展虽然强大，但将AI模型作为数据访问的入口，安全必须放在首位。

1. API Key权限最小化：

   • 绝对不要使用具有all权限的超级API Key。
   • 在Kibana中创建一个专属角色，例如gemini_cli_reader。
   • 只授予这个角色对特定索引（如logs-*,app-*）的read（view_index_metadata,read）权限。如果需要使用ES|QL，确保角色包含read和monitor集群权限。
   • 基于这个角色创建API Key。这样即使Key泄露，攻击者也只能访问限定的只读数据。

2. 环境变量管理：

   • 永远不要将ELASTIC_API_KEY等敏感信息硬编码在脚本或提交到版本控制系统。
   • 除了放在shell配置文件，可以考虑使用更专业的秘密管理工具，如pass,1password,vault，或者使用Shell的export仅在需要时临时设置。
   • 在共享服务器或容器环境中，使用Docker secrets或Kubernetes Secrets来注入环境变量。

3. 审计与监控：

   • 启用Elasticsearch的审计日志功能，记录所有通过此API Key进行的查询操作。定期检查审计日志，监控是否有异常或大量的查询行为。
   • 在Kibana中，你可以通过Stack Management > Security > Audit Logging来配置和查看。

4. 网络隔离：

   • 确保你的Elasticsearch集群部署在受保护的网络环境中，MCP Server的端点 (ELASTIC_MCP_URL) 不直接暴露在公网。
   • 如果可能，将运行Gemini CLI的环境（如开发机）与生产Elasticsearch集群之间的网络访问限制在最小必要范围。

5. 理解“实验性”状态：

   • 当前扩展标记为“实验性”，意味着API、功能、甚至安全性可能在未来版本中发生不兼容的变更。
   • 不建议在核心生产流程或处理极端敏感数据的场景中完全依赖此工具。应将其视为一个强大的辅助探索和开发工具，而非最终生产应用的数据访问层。

我个人在测试和使用中的体会是，gemini-cli-elasticsearch最大的价值在于它模糊了“数据查询”和“自然语言思考”之间的界限。它不是一个完美的产品，自然语言转换的准确性、对复杂嵌套查询的支持都还有提升空间。但在数据探索、快速验证想法、甚至是教育新人理解Elasticsearch数据结构的场景下，它能节省大量查阅文档和编写样板代码的时间。最关键的是，它提供了一种全新的、以对话为中心的数据交互范式，这或许才是其作为“实验性”项目最值得期待的未来。在使用时，保持耐心，从简单查询开始，逐步构建复杂的对话，并始终将安全配置放在心上。