本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

[OpenSearch MCP 伺服器](https://github.com/opensearch-project/opensearch-mcp-server-py) (`opensearch-mcp-server-py`) 是 OpenSearch [模型內容通訊協定](https://modelcontextprotocol.io)的開放原始碼實作。它將 OpenSearch APIs 公開為 AI 助理和代理程式架構可以直接呼叫的工具，因此您可以提出問題，例如*「我的叢集中存在哪些索引？」* 或*「顯示過去一小時最慢的查詢」*，客服人員會代表您處理 API 呼叫。

伺服器可與受管 OpenSearch Service 網域和 OpenSearch Serverless 集合搭配使用。您可以將其連接到編碼 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 Service 網域、OpenSearch Serverless 集合或自我管理的 OpenSearch 叢集。
+ 具有呼叫您要公開之 OpenSearch APIs 許可的登入資料。如需 OpenSearch Service 網域的 IAM 政策，請參閱 [身分型政策](ac.md#ac-types-identity)。如需 OpenSearch Serverless 資料存取政策，請參閱 [Amazon OpenSearch Serverless 的資料存取控制](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 Service 網域**  

```
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 Serverless 集合**  
設定 ，`AWS_OPENSEARCH_SERVERLESS=true`讓伺服器使用`aoss`服務名稱而非 簽署請求`es`。確保透過集合上的資料存取政策授予委託人存取權 （請參閱 [Amazon OpenSearch Serverless 的資料存取控制](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 Service 網域，請檢閱連接到角色的網域存取政策和 IAM 政策。對於 OpenSearch Serverless，請檢閱集合的資料存取政策。

**OpenSearch Serverless 的簽章不相符錯誤**  
確定`AWS_OPENSEARCH_SERVERLESS=true`已設定 （或在`is_serverless: true`多模式中）。如果沒有它，伺服器會使用`es`服務名稱而非 來簽署`aoss`。

**您需要的工具無法使用**  
檢查它是否位於非預設類別中，並在 YAML 組態`enabled_categories`中使用 `OPENSEARCH_ENABLED_CATEGORIES`或 啟用它。

如需進一步協助，請在 [opensearch-mcp-server-py 儲存庫](https://github.com/opensearch-project/opensearch-mcp-server-py/issues)中開啟問題。

## 其他資源
<a name="mcp-server-more-information"></a>
+ GitHub 上的 [opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py) – 來源、問題和版本備註。
+ [使用者指南](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md) – 完整的組態參考，包括串流傳輸和 Kubernetes 部署。
+ [Strands Agents](https://strandsagents.com) – 具有內建 MCP 支援的 AWS原生代理程式 SDK。
+ [LangGraph](https://github.com/langchain-ai/langgraph) – 具狀態代理程式的低階協同運作架構。
+ [OpenSearch 代理程式技能](opensearch-agent-skills.md) – 任務導向工作流程的配套技能集合。