View a markdown version of this page

OpenSearch MCP 伺服器 - Amazon OpenSearch Service
先決條件安裝身分驗證安全考量疑難排解其他資源

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

OpenSearch MCP 伺服器

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

伺服器可與受管 OpenSearch Service 網域和 OpenSearch Serverless 集合搭配使用。您可以將其連接到編碼 IDEs(Kiro、Claude Code、Cursor)、桌面 AI 助理 (Claude Desktop) 和代理程式架構 (Strands Agents、LangGraph)。

先決條件

  • Python 3.10 或更新版本。

  • uv （建議） 或 pip。

  • 可連線的 OpenSearch 端點：OpenSearch Service 網域、OpenSearch Serverless 集合或自我管理的 OpenSearch 叢集。

  • 具有呼叫您要公開之 OpenSearch APIs 許可的登入資料。如需 OpenSearch Service 網域的 IAM 政策，請參閱 身分型政策。如需 OpenSearch Serverless 資料存取政策，請參閱 Amazon OpenSearch Serverless 的資料存取控制。

安裝

使用 執行伺服器 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 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許可。如需範例政策其他範例政策，請參閱 。

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 的資料存取控制)。

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 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 儲存庫中開啟問題。

其他資源