View a markdown version of this page

OpenSearch MCP 服务器 - 亚马逊 OpenSearch 服务
先决条件安装身份验证安全注意事项问题排查其他资源

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

OpenSearch MCP 服务器

OpenSearch MCP 服务器 (opensearch-mcp-server-py) 是模型上下文协议的 OpenSearch开源实现。它以 AI 助手和代理框架可以直接调用的工具 OpenSearch APIs 形式公开，因此你可以问诸如 “我的集群中存在哪些索引？” 之类的问题 或者 “向我显示过去一小时以来最慢的查询”，代理将代表您处理 API 调用。

该服务器同时使用托管 OpenSearch 服务域和 OpenSearch 无服务器集合。你可以将其连接到编码 IDEs （Kiro、Claude Code、Cursor）、桌面 AI 助手（Claude Desktop）和代理框架（Strands Agents，）。 LangGraph

先决条件

  • Python 3.10 或更高版本。

  • uv（推荐）或pip。

  • 可访问的 OpenSearch 终端节点： OpenSearch 服务域、 OpenSearch 无服务器集合或自管理 OpenSearch 集群。

  • 有权调用 OpenSearch APIs 您要公开的凭据。有关 OpenSearch 服务域的 IAM 政策，请参阅基于身份的策略。有关 OpenSearch 无服务器数据访问策略，请参阅Amazon OpenSearch 无服务器的数据访问控制。

安装

使用以下命令运行服务器uvx（无需安装）或在本地安装：

# Run directly with uvx (recommended – no install step)
uvx opensearch-mcp-server-py

# Or install with pip
pip install opensearch-mcp-server-py

大多数用户将自己的 IDE 或 AI 助手配置为自动启动服务器。有关示例与代理框架一起使用，请参阅在编码 IDE 中进行配置和。

身份验证

通过环境变量（单集群模式）或在 YAML 配置文件（多集群模式）中按集群配置身份验证。服务器按以下优先顺序应用身份验证方法：无身份验证、基于标头、IAM 角色、基本身份验证、访问密钥。 AWS

IAM 角色 (Sigv4) — 建议用于服务域 OpenSearch 
export OPENSEARCH_URL="https://your-domain-endpoint"
export AWS_IAM_ARN="arn:aws:iam::123456789012:role/YourOpenSearchRole"
export AWS_REGION="us-east-1"

该角色必须具有调用服务器 OpenSearch APIs 使用的权限。有关策略示例其他示例策略，请参阅。

AWS 凭证或个人资料
export OPENSEARCH_URL="https://your-domain-endpoint"
export AWS_REGION="us-east-1"
export AWS_PROFILE="your-aws-profile"
OpenSearch 无服务器集合

设置AWS_OPENSEARCH_SERVERLESS=true为服务器使用aoss服务名称而不是服务名称来签署请求es。确保通过对馆藏的数据访问策略向委托人授予访问权限（请参阅Amazon OpenSearch 无服务器的数据访问控制）。

export OPENSEARCH_URL="https://collection-id.us-east-1.aoss.amazonaws.com"
export AWS_OPENSEARCH_SERVERLESS="true"
export AWS_REGION="us-east-1"
export AWS_PROFILE="your-aws-profile"
基本身份验证
export OPENSEARCH_URL="https://your-domain-endpoint"
export OPENSEARCH_USERNAME="username"
export OPENSEARCH_PASSWORD="password"
重要

不要在可能签入源代码管理的配置文件中嵌入密码。使用操作系统的密钥管理器或 shell 环境来提供凭据。

安全注意事项

MCP 服务器使用您提供的凭据运行。无论这些凭证有权执行什么操作，AI 助手都可能代表你触发。请遵循以下做法：

  • 使用权限最低的凭证。创建专用 IAM 角色或 OpenSearch 用户，其范围仅限于代理所需的索引和操作。避免重复使用管理员凭据。

  • 将开发和生产分开。将服务器指向非生产群集进行探索。当需要生产访问权限时，使用带有显式集群名称的多模式。

  • 筛选工具。禁用您的工作流程不需要的工具类别。设置OPENSEARCH_DISABLED_CATEGORIES=core_tools为禁用默认设置，或OPENSEARCH_ENABLED_CATEGORIES用于仅启用特定类别。

  • 保护凭证。与静态访问密钥相比，更喜欢 AWS 配置文件和 IAM 角色。切勿在源代码管理中向配置文件提交机密。

  • 查看工具输出。MCP 工具的响应作为上下文反馈到语言模型。避免对包含您不想向 AI 提供商公开的敏感数据的索引运行服务器。

问题排查

助手看不到任何 OpenSearch 工具

确认您的配置文件是有效的 JSON，然后完全重启客户端。大多数客户端仅在启动时加载 MCP 服务器。

工具调用返回 403 禁止

您的凭证无权访问该工具正在调用的 API。对于 OpenSearch 服务域，请查看附加到您的角色的域访问策略和 IAM 策略。对于 OpenSearch 无服务器，请查看集合的数据访问策略。

Serverless 的签名不匹配错误 OpenSearch

确保AWS_OPENSEARCH_SERVERLESS=true已设置（或is_serverless: true在多模式下）。如果没有它，服务器将使用es服务名称而不是服务名称进行签名aoss。

你需要的工具不可用

检查它是否属于非默认类别，并使用OPENSEARCH_ENABLED_CATEGORIES或在您的 YAML enabled_categories 配置中启用它。

要获得更多帮助，请在opensearch-mcp-server-py 存储库中打开一个问题。

其他资源