opensearch-project/opensearch-mcp-server-py

- Installing opensearch-mcp-server-py
- Available tools
- User Guide
- Agent Memory
- Contributing
- Code of Conduct
- License
- Copyright
OpenSearch MCP Server
**opensearch-mcp-server-py** is a Model Context Protocol (MCP) server for OpenSearch that enables AI assistants to interact with OpenSearch clusters. It provides a standardized interface for AI models to perform operations like searching indices, retrieving mappings, and managing shards through both stdio and streaming (SSE/Streamable HTTP) protocols.
**Key features:**
- Seamless integration with AI assistants and LLMs through the MCP protocol
- Support for both stdio and streaming server transports (SSE and Streamable HTTP)
- Built-in tools for common OpenSearch operations
- Dynamic per-call connection parameters for targeting different clusters without server reconfiguration
- Easy integration with Claude Desktop and LangChain
- Secure authentication using basic auth, IAM roles, header-based auth, and OpenSearch mTLS
For detailed setup, including Kubernetes deployment and mTLS configuration, see the User Guide.
Installing opensearch-mcp-server-py
Opensearch-mcp-server-py can be installed from PyPI via pip:
Zero-Config Setup
The server can be started with no environment variables at all. Agents provide connection details dynamically on each tool call:
With this setup, agents pass opensearch_url and authentication parameters directly when calling any tool. This is useful when agents discover endpoints from a knowledge base, runbook, or SOP, or when a single agent needs to work with multiple clusters in one session. See Dynamic Connection Parameters for details.
Available Tools
By default, only **core tools** are enabled to provide essential OpenSearch functionality:
Core Tools (Enabled by Default)
Core tools are grouped under the core_tools category and can be disabled at once using OPENSEARCH_DISABLED_CATEGORIES=core_tools. Avoid creating custom categories with this name as they will override the built-in category.
- ListIndexTool: Lists all indices in OpenSearch with full information including docs.count, docs.deleted, store.size, etc. If an index parameter is provided, returns detailed information about that specific index.
- IndexMappingTool: Retrieves index mapping and setting information for an index in OpenSearch.
- SearchIndexTool: Searches an index using a query written in query domain-specific language (DSL) in OpenSearch.
- GetShardsTool: Gets information about shards in OpenSearch.
- ClusterHealthTool: Returns basic information about the health of the cluster.
- CountTool: Returns number of documents matching a query.
- ExplainTool: Returns information about why a specific document matches (or doesn't match) a query.
- MsearchTool: Allows to execute several search operations in one request.
- [GenericOpenSearchApiTool]: A flexible tool that can call any OpenSearch API endpoint with custom paths, methods, query parameters, and request bodies. Reduces tool explosion by providing a single interface for all OpenSearch APIs.
Additional Tools (Disabled by Default)
The following tools are available but disabled by default. To enable them, see the Tool Filter section in the User Guide.
- GetClusterStateTool: Gets the current state of the cluster including node information, index settings, and more.
- GetSegmentsTool: Gets information about Lucene segments in indices, including memory usage, document counts, and segment sizes.
- CatNodesTool: Gets information about nodes in the OpenSearch cluster, including system metrics like CPU usage, memory, disk space, and node roles.
- GetNodesTool: Gets detailed information about nodes in the OpenSearch cluster, including static information like host system details, JVM info, processor type, node settings, thread pools, installed plugins, and more.
- GetIndexInfoTool: Gets detailed information about an index including mappings, settings, and aliases. Supports wildcards in index names.
- GetIndexStatsTool: Gets statistics about an index including document count, store size, indexing and search performance metrics.
- GetQueryInsightsTool: Gets query insights from the /\_insights/top_queries endpoint, showing information about query patterns and performance.
- GetNodesHotThreadsTool: Gets information about hot threads in the cluster nodes from the /\_nodes/hot_threads endpoint.
- GetAllocationTool: Gets information about shard allocation across nodes in the cluster from the /\_cat/allocation endpoint.