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

# OpenSearch MCP 服务器
<a name="opensearch-mcp-server"></a>

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

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

## 先决条件
<a name="mcp-server-prerequisites"></a>
+ Python 3.10 或更高版本。
+ [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)（推荐）或`pip`。
+ 可访问的 OpenSearch 终端节点： OpenSearch 服务域、 OpenSearch 无服务器集合或自管理 OpenSearch 集群。
+ 有权调用 OpenSearch APIs 您要公开的凭据。有关 OpenSearch 服务域的 IAM 政策，请参阅[基于身份的策略](ac.md#ac-types-identity)。有关 OpenSearch 无服务器数据访问策略，请参阅[Amazon OpenSearch 无服务器的数据访问控制](serverless-data-access.md)。

## 安装
<a name="mcp-server-install"></a>

使用以下命令运行服务器`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 助手配置为自动启动服务器。有关示例[与代理框架一起使用](mcp-server-configure-frameworks.md)，请参阅[在编码 IDE 中进行配置](mcp-server-configure-ide.md)和。

## 身份验证
<a name="mcp-server-authentication"></a>

通过环境变量（单集群模式）或在 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 使用的权限。有关策略示例[其他示例策略](ac.md#ac-samples)，请参阅。

**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 无服务器的数据访问控制](serverless-data-access.md)）。  

```
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 环境来提供凭据。

## 安全注意事项
<a name="mcp-server-security"></a>

MCP 服务器使用您提供的凭据运行。无论这些凭证有权执行什么操作，AI 助手都可能代表你触发。请遵循以下做法：
+ **使用权限最低的凭证。**创建专用 IAM 角色或 OpenSearch 用户，其范围仅限于代理所需的索引和操作。避免重复使用管理员凭据。
+ **将开发和生产分开。**将服务器指向非生产群集进行探索。当需要生产访问权限时，使用带有显式集群名称的多模式。
+ **筛选工具。**禁用您的工作流程不需要的工具类别。设置`OPENSEARCH_DISABLED_CATEGORIES=core_tools`为禁用默认设置，或`OPENSEARCH_ENABLED_CATEGORIES`用于仅启用特定类别。
+ **保护凭证。**与静态访问密钥相比，更喜欢 AWS 配置文件和 IAM 角色。切勿在源代码管理中向配置文件提交机密。
+ **查看工具输出。**MCP 工具的响应作为上下文反馈到语言模型。避免对包含您不想向 AI 提供商公开的敏感数据的索引运行服务器。

## 问题排查
<a name="mcp-server-troubleshooting"></a>

**助手看不到任何 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 存储库](https://github.com/opensearch-project/opensearch-mcp-server-py/issues)中打开一个问题。

## 其他资源
<a name="mcp-server-more-information"></a>
+ [opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py)on GitHub — 来源、问题和发行说明。
+ [用户指南](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md) — 完整的配置参考，包括流媒体传输和 Kubernetes 部署。
+ [Strands Agen](https://strandsagents.com) ts — 具有内置 MCP AWS支持的本机代理 SDK。
+ [LangGraph](https://github.com/langchain-ai/langgraph)— 有状态代理的低级编排框架。
+ [OpenSearch 特工技能](opensearch-agent-skills.md)— 适用于以任务为中心的工作流程的配套技能集。