一文掌握mcp-server-elasticsearch配置全解JSON5、环境变量插值与自定义工具【免费下载链接】mcp-server-elasticsearchElasticsearch Model Context Protocol (MCP) server项目地址: https://gitcode.com/gh_mirrors/mc/mcp-server-elasticsearchmcp-server-elasticsearch 是官方推出的Elasticsearch MCP Server它基于 Model Context ProtocolMCP协议让 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工具用途list_indices列出所有可用索引get_mappings获取指定索引的字段映射search用 Query DSL 执行搜索esql执行 ES|QL 查询get_shards获取分片信息它还支持两种传输协议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它全部由环境变量驱动环境变量说明ES_URL集群地址如https://your-cluster:9200必填ES_API_KEYAPI Key 认证与用户名/密码二选一ES_USERNAME/ES_PASSWORDBasic 认证凭据ES_SSL_SKIP_VERIFY设为true跳过证书校验仅限开发/测试环境HTTP_ADDRESSHTTP 模式监听地址默认127.0.0.1:8080CONTAINER_MODE容器模式自动把localhost改写为host.docker.internal以 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.json5esql 类型—— 把一条 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一张表帮你选维度stdiostreamable-HTTP典型场景Claude Desktop、Cursor、VS Code 本地直连Web 集成、有状态会话、多客户端并发部署方式客户端直接拉起进程常驻容器/mcp端点 /ping健康检查认证传递环境变量环境变量 或 请求头Authorization透传容器模式支持默认监听0.0.0.0:8080Dockerfile内置CONTAINER_MODEtrueHTTP 模式下每个请求头里的Authorization还会被透传给 Elasticsearch实现见 src/servers/elasticsearch/mod.rs意味着不同客户端可以用各自的身份访问集群。七、常见配置问题排查清单env variable ES_URL not defined—— 必填变量未注入检查客户端的env配置连接超时—— 容器内访问宿主机请用host.docker.internal并开启容器模式云环境检查安全组认证 401—— 确认用的是ES_API_KEY还是用户名/密码两者只能配一组自签证书报错—— 仅限开发环境可设ES_SSL_SKIP_VERIFYtrue健康检查—— HTTP 模式可curl http://host:8080/ping返回pong即正常更多细节可查看 README.md 与 docs/CONTRIBUTING.md。八、小结 三句话记住 mcp-server-elasticsearch 的配置精髓环境变量驱动ES_URL API Key 即可零配置跑通JSON5 配置 ${VAR:default}插值配置入库、密钥运行时注入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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考