OpenSearch MCP Server – Search Cluster Access
The OpenSearch MCP Server exposes OpenSearch cluster operations to MCP-compatible AI assistants. It lets agents search indexes, inspect mappings, check cluster health, count documents, and call OpenSearch APIs through structured MCP tools instead of hand-written REST requests.
Overview
OpenSearch MCP Server is the official OpenSearch Project MCP server for connecting AI assistants to OpenSearch clusters. It is designed for clients such as Claude Desktop, Cursor, Kiro, or other MCP-compatible tools that need live access to search and observability data stored in OpenSearch.
The server translates MCP tool calls into OpenSearch REST API calls and returns structured results. This allows an AI agent to work with cluster data without generating raw HTTP requests itself.
What the MCP server enables
The standalone opensearch-mcp-server-py package includes core tools enabled by default for common cluster work. These include listing indexes, retrieving index mappings, searching with OpenSearch Query DSL, checking cluster health, counting documents, explaining document matches, running multi-search requests, getting shard information, and using a generic OpenSearch API tool.
Additional tool categories are available but disabled by default. These include cluster and index inspection tools, search relevance tools, and skills-based analysis tools such as data distribution and log pattern analysis. Tool categories can be enabled or disabled through documented configuration.
When to use it
Use this MCP server when an AI assistant needs to explore OpenSearch data, support incident or observability workflows, inspect index structure, troubleshoot cluster state, or build internal search assistants. It is especially useful when an assistant needs to connect to different OpenSearch clusters such as development, staging, and production in one workflow.
Connection and authentication
The standalone server supports local stdio use and streaming transports for remote deployments. A zero-configuration local setup can start the server with uvx opensearch-mcp-server-py; connection details such as opensearch_url, username, password, AWS settings, or SSL options can be passed dynamically per tool call. The server also supports configuration through environment variables such as OPENSEARCH_URL, OPENSEARCH_USERNAME, OPENSEARCH_PASSWORD, OPENSEARCH_NO_AUTH, AWS_REGION, AWS_IAM_ARN, AWS_PROFILE, AWS_OPENSEARCH_SERVERLESS, OPENSEARCH_SSL_VERIFY, and OPENSEARCH_TIMEOUT.
OpenSearch also provides an in-cluster MCP Streamable HTTP endpoint at /_plugins/_ml/mcp for clusters where MCP server functionality is enabled. That endpoint is introduced in OpenSearch 3.3 and uses stateless HTTP POST communication rather than a persistent SSE connection.
Key considerations
Access is limited by the credentials and permissions used to connect to the target OpenSearch cluster. The project documents support for basic authentication, AWS IAM roles, AWS profile credentials, header-based authentication, mTLS, and anonymous access. Production deployments should use least-privilege credentials and avoid giving agents unnecessary access to write-capable or administrative OpenSearch APIs. Some additional tools are disabled by default and should be enabled only when the agent workflow requires them.
Supported Transports
streamable_http
URL: https://${OPENSEARCH_ENDPOINT}/_plugins/_ml/mcp
stdio
Command: uvx
Args:
opensearch-mcp-server-py
Frequently Asked Questions
- When should an AI agent use the OpenSearch MCP Server?
- Use it when an agent needs live access to OpenSearch data for search, observability, troubleshooting, index exploration, or internal data-assistant workflows. It is useful for querying indexes, understanding mappings, checking cluster health, and working across multiple OpenSearch environments.
- What does this MCP server add to an AI agent's capabilities?
- It gives the agent structured MCP tools for OpenSearch operations, including listing indexes, retrieving mappings, searching with OpenSearch Query DSL, counting documents, checking cluster health, explaining search matches, running multi-search requests, and getting shard information.
- What can the AI agent access or manage through this server?
- The standalone server can access self-managed OpenSearch, Amazon OpenSearch Service, and Amazon OpenSearch Serverless collections. The exact operations available depend on enabled tool categories and the permissions of the credentials used to connect to the cluster.
- How is authentication configured for this MCP server?
- Authentication can be provided through dynamic per-call parameters or server configuration. Documented options include basic authentication, AWS IAM roles, AWS profile credentials, header-based authentication, mTLS, and anonymous access. Secrets should be supplied through environment variables or a protected configuration file, not embedded directly in client prompts.
- Which transport should be used for this MCP server?
- Use `stdio` with `uvx opensearch-mcp-server-py` for local desktop clients and simple agent setups. Use Streamable HTTP for the OpenSearch in-cluster endpoint at `/_plugins/_ml/mcp` when MCP server functionality is enabled in an OpenSearch 3.3 or later cluster and the client supports that transport.