OpenSearch MCP Server

Content

The OpenSearch MCP Server is the official Model Context Protocol server maintained by the OpenSearch Project. It bridges AI assistants and OpenSearch clusters — self-managed, Amazon OpenSearch Service, or OpenSearch Serverless — so an agent can list indices, read mappings, run Query DSL and PPL searches, inspect shards and cluster health, and call arbitrary OpenSearch APIs over both stdio and streaming (SSE / Streamable HTTP) transports.

The project is written in Python, distributed as the PyPI package opensearch-mcp-server-py (v0.10.0, Python >=3.10), and licensed under Apache 2.0. It supports single- and multi-cluster configurations and multiple authentication methods (basic auth, AWS IAM roles, AWS credentials/profiles, and header-based auth). Full documentation lives in the USER_GUIDE.md.

Source Review

The following real repository and package sources were fetched and reviewed for this entry:

• README.md — install command, zero-config and env-var client config blocks, the core/opt-in tool catalog, tool categories, and transport support.
• USER_GUIDE.md — stdio vs streaming modes, single/multi-cluster (--mode) setup, authentication methods, and per-cluster config.
• PyPI: opensearch-mcp-server-py — package name and version (0.10.0) and requires_python >=3.10.
• LICENSE.txt — Apache License 2.0.

Repository facts confirmed at review time: official opensearch-project organization, default branch main, not archived, actively maintained, and released as opensearch-mcp-server-py v0.10.0 on PyPI.

Features

• Index discovery — ListIndexTool lists indices with docs counts and store sizes; IndexMappingTool returns mappings and settings.
• Search — SearchIndexTool runs Query DSL, MsearchTool batches multiple searches, CountTool counts matches, and ExplainTool explains why a document matches.
• Cluster inspection — GetShardsTool and ClusterHealthTool report shard and cluster health; opt-in tools cover nodes, cluster state, segments, allocation, tasks, and query insights.
• Generic API access — GenericOpenSearchApiTool calls any OpenSearch API endpoint with a custom path, method, query params, and body, reducing tool explosion.
• Observability (opt-in) — PPLQueryTool runs Piped Processing Language queries with jdbc/csv/raw output.
• Search relevance (opt-in) — tools to create, search, and delete search configurations, query sets, judgment lists, and experiments (PAIRWISE_COMPARISON, POINTWISE_EVALUATION, HYBRID_OPTIMIZER).
• Agent memory (opt-in) — memory and agentic-memory tools give the agent persistent, semantically indexed memory backed by OpenSearch.
• Tool filtering — enable categories via OPENSEARCH_ENABLED_CATEGORIES or a config file; only core tools are on by default.
• Multiple transports & clusters — stdio (default) or streaming (SSE / Streamable HTTP), and single- or multi-cluster via --mode single|multi.
• Flexible auth — basic auth, AWS IAM roles, AWS credentials/profiles, header-based auth, and OpenSearch Serverless.

Installation

Run the published package with uvx (no clone required):

uvx opensearch-mcp-server-py

Add it to an MCP client (e.g. Claude Desktop's claude_desktop_config.json) with basic auth:

{
  "mcpServers": {
    "opensearch-mcp-server": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"],
      "env": {
        "OPENSEARCH_URL": "<your_opensearch_domain_url>",
        "OPENSEARCH_USERNAME": "<your_username>",
        "OPENSEARCH_PASSWORD": "<YOUR_PASSWORD>"
      }
    }
  }
}

Or run zero-config and let the agent pass connection details per tool call (useful for multi-cluster sessions):

{
  "mcpServers": {
    "opensearch": {
      "command": "uvx",
      "args": ["opensearch-mcp-server-py"]
    }
  }
}

Key environment variables

Every connection parameter can also be supplied per tool call (opensearch_url, opensearch_username, etc.), which overrides the environment — see the User Guide's Dynamic Connection Parameters.

Use Cases

• Conversational search — ask natural-language questions and have the agent build Query DSL or PPL against your indices.
• Index and mapping exploration — let an LLM enumerate indices, fields, and settings before writing queries or ingest pipelines.
• Cluster operations — inspect shard allocation, cluster health, nodes, and long-running tasks during triage.
• Search-relevance tuning (opt-in) — create query sets, judgment lists, and experiments to evaluate and optimize search configurations.
• Multi-cluster workflows — run one server in --mode multi and let the agent target different clusters per request.

Safety and Privacy

• Generic API tool is powerful. GenericOpenSearchApiTool can call any OpenSearch endpoint, including write/delete operations, within the credential's permissions — treat it like direct cluster API access.
• Opt-in tools mutate data. Memory/agentic-memory and search-relevance tools can create and delete stored objects (including delete-by-query); enable categories deliberately.
• RBAC is the boundary. Scope the OpenSearch user/role to least privilege; tool naming is not access control. Prefer a non-production cluster for autonomous agents.
• Data flows to the model. Documents, mappings, and search results are returned to the LLM/MCP client and can include PII; cluster-introspection tools expose infrastructure metadata.
• Credential hygiene. Basic-auth passwords, AWS IAM ARNs, and AWS profiles live in the client config or per-call parameters — keep config out of version control and restrict access.
• Network exposure. In streaming mode the server opens a port; do not bind it to a public interface without authentication in front of it.

Duplicate Check

No existing entry in the directory matches this server. A search of all directory entries for "opensearch" across slugs, titles, repository URLs, and install commands returned no dedicated entry (the term appears only inside unrelated servers that list OpenSearch as one supported datasource), and there is no prior entry pointing at github.com/opensearch-project/opensearch-mcp-server-py or the PyPI package opensearch-mcp-server-py. This is therefore a net-new, non-duplicate entry.

• Source repositorygithub.com 2026-07-07T23:16:18-07:00
• Documentationgithub.com
• Websiteopensearch.org
• Submitted by davion-knight2026-07-07