OpenSearch MCP Server
Official MCP server from the OpenSearch project exposes a cluster to agents: indexes, mappings, DSL search and shard state.
- 158 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- The generic tool calls any API endpoint: account permissions decide what the agent can change or delete.
- The cluster address and credentials go to the server and, in network mode, travel in requests.
Install
- Works in
Manual install
pip install opensearch-mcp-server-pyThe first README Install command, a PyPI package. Run without installing through `uvx opensearch-mcp-server-py` in MCP client settings.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The generic tool calls any API endpoint: account permissions decide what the agent can change or delete.
- The cluster address and credentials go to the server and, in network mode, travel in requests.
This is third-party code. Review the repository files before installing.
What it does
The `opensearch-mcp-server-py` MCP server connects an agent to an OpenSearch cluster. Core tools are on by default: index listing, mappings, DSL search, document count, match explanation, multi-search, shard state and cluster health. A separate generic tool calls any API endpoint with a chosen method and body. Extra groups are enabled through environment variables: node and segment diagnostics, PPL queries, a search relevance workbench, log analytics and agent memory kept in the cluster. It runs over stdio and streaming HTTP (SSE and Streamable HTTP). Connection details come from variables, a config file or from the agent on each call.
Who it is for. Engineers who query logs and data in OpenSearch and want to ask an agent about them in plain language.
Good fit when
- An agent investigates an incident through logs in an index.
- You want to know why a document missed the results.
- Shard state and cluster health are checked without the console.
- One agent works with several clusters at once.
Not a fit when
- The cluster cannot be exposed to an agent even read-only.
- A ready dashboard is needed rather than a conversation with data.
- Production access goes to humans only, with every write confirmed.
Example request
List the cluster indexes, find errors in the logs for the last hour and explain why the expected document is missing from results.MCP
- Transport
- stdio, http
- Authentication
- API key
Environment variables
`OPENSEARCH_URL`- OpenSearch cluster address. Without it the agent supplies the address on each call.
`OPENSEARCH_ENABLED_CATEGORIES`- Extra tool groups to enable, for example `observability`.
`OPENSEARCH_DISABLED_CATEGORIES`- Groups to turn off, for example `core_tools`.
Limitations
The generic tool calls any API endpoint, so the OpenSearch account's permissions decide what the agent can change or delete. Give a separate user a read-only role until more is needed. Without environment variables the server expects connection details from the agent on every call, and over a network address and credentials travel in requests, so protect the channel. Extra tool groups are enabled by hand and do not replace cluster permission setup.
How to disable. Remove the server entry from the MCP client settings and stop your HTTP instance if you ran one. Revoke the OpenSearch role and account separately.
FAQ
Which tools are on by default?
The core set: `ListIndexTool`, `IndexMappingTool`, `SearchIndexTool`, `GetShardsTool`, `ClusterHealthTool`, `CountTool`, `ExplainTool`, `MsearchTool` and `GenericOpenSearchApiTool`. Other groups are enabled separately.
Can it start without environment variables?
Yes. In the zero-config mode the agent passes `opensearch_url` and authentication parameters on every call, which suits work with several clusters.
How do I enable extra groups?
Through `OPENSEARCH_ENABLED_CATEGORIES`, for example `observability` for PPL queries, or through the tool filter from the user guide.
How do I turn off the core tools?
Set `OPENSEARCH_DISABLED_CATEGORIES=core_tools` and the whole core group switches off at once.
Which authentication is supported?
Basic auth, IAM roles, header-based auth and mutual TLS (mTLS).
Discussion
No questions or reviews yet.
Related
MCP serversElasticsearch MCP connects multiple search clusters, with an explicit target name and access scoped to the supplied credentials.
An MCP server gives agents search and answers over local documents using hybrid retrieval, reranking and section links.
Official MongoDB MCP server: queries and aggregations, index management, Atlas clusters and local deployments
An MCP server for searching and downloading academic papers from arXiv, PubMed, bioRxiv, Semantic Scholar and other open sources
An MCP server with a toolbox for global briefs: markets, SEC filings, conflict, climate and news from open sources
MCP server that gives an agent access to MySQL: schema inspection and queries, read-only by default, writes behind flags
README in short
Official MCP server for OpenSearch that runs over stdio and the network and connects to a cluster through several authentication methods.