企业官网建设流程全解析

一文掌握mcp-server-elasticsearch配置全解：JSON5、环境变量插值与自定义工具

【免费下载链接】mcp-server-elasticsearchElasticsearch Model Context Protocol (MCP) server项目地址: https://gitcode.com/gh_mirrors/mc/mcp-server-elasticsearch

mcp-server-elasticsearch 是官方推出的Elasticsearch MCP Server：它基于 Model Context Protocol（MCP）协议，让 AI Agent 通过自然语言直接查询、分析和检索你的 Elasticsearch 数据，无需编写任何自定义 API。本文带你完整掌握它的配置体系：JSON5 配置文件、${VAR}环境变量插值、内置工具的过滤与自定义工具扩展。

⚠️ 注意：该 Server 已标记为弃用，后续仅接收关键安全更新，官方建议迁移到 Elastic Agent Builder 的 MCP 端点（Elastic 9.2.0+ 可用）。了解其配置机制依然对你理解 MCP 工具生态很有价值。

一、先认识它：内置工具一览

Server 启动后会向 Agent 暴露 5 个只读工具，定义见 src/servers/elasticsearch/base_tools.rs：

它还支持两种传输协议：

• stdio：客户端直接拉起进程，适合 Claude Desktop、Cursor、VS Code 等本地 MCP 客户端
• streamable-HTTP：监听 HTTP 端点（默认127.0.0.1:8080，端点为/mcp，健康检查为/ping），适合 Web 集成与多客户端并发；旧的 SSE 模式已弃用

协议入口与启动逻辑见 src/lib.rs 与 src/protocol/。

二、快速开始：用环境变量"零配置"启动

🚀 不传配置文件时，Server 会使用一段内置的默认配置（源码见 src/lib.rs），它全部由环境变量驱动：

以 Docker 镜像运行（构建脚本见 Makefile 与 Dockerfile）：

# stdio 模式 docker run -i --rm -e ES_URL -e ES_API_KEY \ docker.elastic.co/mcp/elasticsearch stdio # HTTP 模式 docker run --rm -e ES_URL -e ES_API_KEY -p 8080:8080 \ docker.elastic.co/mcp/elasticsearch http

启动参数定义在 src/cli.rs：两种模式都支持-c/--config指定配置文件，HTTP 模式还支持--address与已弃用的--sse开关。

三、JSON5 配置文件详解

想要更精细的控制？传一个 JSON5 配置文件即可（stdio -c my.json5或http -c my.json5）。仓库自带一份注释详尽的示例 elastic-mcp.json5，核心结构如下：

{ // JSON5 支持注释，比 JSON 友好得多 "elasticsearch": { "url": "${ES_URL}", "api_key": "${ES_API_KEY:}", "username": "${ES_USERNAME:}", "password": "${ES_PASSWORD:}", "ssl_skip_verify": "${ES_SSL_SKIP_VERIFY:false}" } }

选择 JSON5 而非 JSON 的用意很实际：注释方便写说明，多行字符串方便粘贴复杂的 ES|QL 查询（解析逻辑见 src/lib.rs）。认证字段支持"空字符串视为未设置"的宽松处理，所以 API Key 与 Basic 认证可以并存于同一份配置，由环境变量决定哪组生效。

💡 配置文件的完整 Schema 定义在 src/servers/elasticsearch/mod.rs，包括url、api_key、username、password、ssl_skip_verify、tools、prompts等字段。

四、环境变量插值机制：${VAR}与${VAR:default}

🔍 配置中的${...}语法由专门的插值器实现（src/utils/interpolator.rs），规则非常简洁：

• ${VAR}：必填。变量未定义时直接报错，错误信息会带上行号和列号，方便定位
• ${VAR:default}：可选。变量未定义时取冒号后的默认值，如${ES_SSL_SKIP_VERIFY:false}默认false、${ES_API_KEY:}默认为空字符串

示例：

{ "elasticsearch": { "url": "${ES_URL}", // 未设置则启动失败 "ssl_skip_verify": "${ES_SSL_SKIP_VERIFY:false}" // 未设置则用 false } }

这个设计的巧妙之处：配置文件可以安全地放进版本库，敏感值（地址、密钥）全部在运行时经环境变量注入，既不硬编码凭据，又能在不同环境间复用同一份配置。

五、自定义工具：过滤内置工具 + 扩展专属工具

tools字段是配置中最"进阶"的部分（结构定义见 src/servers/elasticsearch/mod.rs），提供两大能力。

1️⃣ 用 include / exclude 裁剪内置工具

"tools": { "exclude": ["search"] // 排除过于宽泛的 search 工具 }

2️⃣ 用 custom 声明自定义工具

自定义工具有两种类型，示例完整代码见 elastic-mcp.json5：

esql 类型—— 把一条 ES|QL 查询封装成带参数的工具：

"custom": { "add-42": { "type": "esql", "description": "Adds 42 to the input value", "query": "row value = ?value | eval result = value + 42 | keep result", "parameters": { "value": { "title": "The value", "type": "number" } } } }

search_template 类型—— 把存储的搜索模板（template_id）或内联模板（template）暴露为工具，参数通过{{param_1}}占位符注入。

自定义工具的价值在于：用配置把业务查询"固化"为语义清晰的工具，让 Agent 调用的是add-42这样的业务动作，而不是裸的 DSL——更可控，也更能体现你希望 Agent 如何使用数据。

六、stdio 还是 HTTP？一张表帮你选

HTTP 模式下，每个请求头里的Authorization还会被透传给 Elasticsearch（实现见 src/servers/elasticsearch/mod.rs），意味着不同客户端可以用各自的身份访问集群。

七、常见配置问题排查清单

• env variable 'ES_URL' not defined—— 必填变量未注入，检查客户端的env配置
• 连接超时—— 容器内访问宿主机请用host.docker.internal并开启容器模式；云环境检查安全组
• 认证 401—— 确认用的是ES_API_KEY还是用户名/密码，两者只能配一组
• 自签证书报错—— 仅限开发环境可设ES_SSL_SKIP_VERIFY=true
• 健康检查—— HTTP 模式可curl http://<host>:8080/ping，返回pong即正常

更多细节可查看 README.md 与 docs/CONTRIBUTING.md。

八、小结

📌 三句话记住 mcp-server-elasticsearch 的配置精髓：

1. 环境变量驱动：ES_URL+ API Key 即可零配置跑通
2. JSON5 配置 +${VAR:default}插值：配置入库、密钥运行时注入
3. tools字段：exclude裁剪内置工具，custom把 ES|QL 与搜索模板变成专属工具

虽然项目本身已进入维护期，但"配置文件 + 环境变量插值 + 工具注册表"这套 MCP Server 配置范式，几乎可以直接迁移到你自研的 MCP 服务中。

【免费下载链接】mcp-server-elasticsearchElasticsearch Model Context Protocol (MCP) server项目地址: https://gitcode.com/gh_mirrors/mc/mcp-server-elasticsearch