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.
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.
- GetLongRunningTasksTool: Gets information about long-running tasks in the cluster, sorted by running time in descending order.
Agentic Memory Tools (Disabled by Default)
The following tools expose the OpenSearch Agentic Memory API — a server-side memory system built into OpenSearch itself. The OpenSearch cluster manages memory containers, sessions, and inference (LLM-based extraction of facts from conversations). These tools require OpenSearch 3.3.0 or later.
When to use: You want OpenSearch to own the full memory lifecycle — including LLM-based inference to extract facts from raw conversations, structured memory types (sessions, working, long-term, history), and server-managed namespacing. Best for production agentic pipelines where memory management should be centralized and not depend on the MCP client.
Setup: You must create a memory container in OpenSearch before using these tools (one-time admin operation requiring LLM connector and embedding model configuration). See Agentic Memory Tools in the Agent Memory Guide.
Enable with OPENSEARCH_ENABLED_CATEGORIES=agentic_memory. When memory_container_id is configured via the agentic_memory config section or OPENSEARCH_MEMORY_CONTAINER_ID environment variable, it is automatically pre-filled in all tool calls.
Observability Tools (Disabled by Default)
Observability tools are grouped under the observability category and can be enabled using OPENSEARCH_ENABLED_CATEGORIES=observability or by adding enabled_categories: [observability] to the config file. Alternatively, enable the analytics category to get both observability and skills tools at once.
- PPLQueryTool: Executes a PPL (Piped Processing Language) query against OpenSearch. PPL provides a pipe-based syntax for querying data (
source=<index> | <command> | <command>), supporting filtering, aggregation, sorting, deduplication, and field selection. Supports jdbc, csv, and raw output formats.
Search Relevance Workbench Tools (Disabled by Default)
Search Relevance Workbench tools are grouped under the search_relevance category and can be enabled at once using OPENSEARCH_ENABLED_CATEGORIES=search_relevance or by adding enabled_categories: [search_relevance] or explicitly adding individual tools to their config file. See the Tool Filter section in the User Guide for additional information about how to filter tools.
Skills Tools (Disabled by Default)
Skills tools are grouped under the skills category and can be enabled at once using OPENSEARCH_ENABLED_CATEGORIES=skills or by adding enabled_categories: [skills] to the config file. Alternatively, enable the analytics category to get both skills and observability tools at once. See the Tool Filter section in the User Guide for additional information about how to filter tools.
- DataDistributionTool: Analyzes data distribution patterns and field value frequencies within OpenSearch indices. Supports both single dataset analysis and comparative analysis between two time periods to identify distribution changes.
- LogPatternAnalysisTool: Detects anomalous log patterns and sequences through comparative analysis between baseline and selection time ranges. Supports log sequence analysis with trace correlation, log pattern difference analysis, and log insights analysis for error detection.
- MetricChangeAnalysisTool: Compares percentile distributions (P50, P90) of all numeric fields between a baseline and a selection time range, then returns the top fields ranked by change score. Useful for identifying which numeric metrics shifted most during an anomaly window.
Memory Tools (Opt-in)
Memory tools give the MCP agent itself persistent, cross-session memory backed by OpenSearch. The agent decides what to save as plain-text statements; OpenSearch stores and semantically indexes them. Enable with MEMORY_TOOLS_ENABLED=true. See the Agent Memory Guide for full setup instructions.
When to use: You want a lightweight, agent-driven memory layer that works with any MCP-compatible IDE (Kiro, Claude Code, Cursor). The agent controls what gets remembered — no LLM connectors or embedding models to configure on the OpenSearch side. Requires Amazon OpenSearch Service (managed domain 2.19+ or Serverless) for automatic semantic enrichment. See the Agent Memory Guide for full setup instructions.
- SaveMemoryTool: Saves facts, decisions, and preferences to persistent storage with automatic semantic enrichment.
- SearchMemoryTool: Searches memories using natural language with recency-aware ranking.
- DeleteMemoryTool: Removes outdated or incorrect memories by document ID.
Tool Parameters
All tools accept the following optional connection parameters that override the server's environment variable configuration on a per-call basis. When all are omitted, the server uses its configured environment variables or cluster config as usual. When you supply opensearch_url, the credentials must come from that same call: the server will not use its own credentials against a URL a caller chose, unless the operator sets OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK=true to share its AWS credentials.
| Parameter | Type | Description |
|---|
opensearch_url | string | OpenSearch endpoint URL. Overrides OPENSEARCH_URL. |
opensearch_username | string | Username for basic auth. Overrides OPENSEARCH_USERNAME. |
opensearch_password | string | Password for basic auth. Overrides OPENSEARCH_PASSWORD. |
opensearch_no_auth | boolean | Connect without authentication. Overrides OPENSEARCH_NO_AUTH. |
aws_region | string | AWS region. Overrides AWS_REGION. |
aws_iam_arn | string | IAM role ARN. Overrides AWS_IAM_ARN. |
aws_profile | string | AWS profile name. Overrides AWS_PROFILE. |
aws_opensearch_serverless | boolean | Use OpenSearch Serverless. Overrides AWS_OPENSEARCH_SERVERLESS. |
opensearch_ssl_verify | boolean | Set true to require SSL certificate verification. A false value is ignored, since only OPENSEARCH_SSL_VERIFY may disable it. |
opensearch_timeout | integer | Connection timeout in seconds. Overrides OPENSEARCH_TIMEOUT. |
This allows agents to dynamically target different clusters per tool call without reconfiguring the server (single mode only). Credentials must come from the same call as the URL, unless OPENSEARCH_ALLOW_AMBIENT_AWS_FALLBACK=true lets the server sign caller-supplied URLs with its own AWS credentials. OPENSEARCH_SSRF_GUARD=true restricts caller-supplied URLs to public HTTPS addresses. See Dynamic Connection Parameters in the User Guide for details and examples.
In addition to the common connection parameters above, each tool accepts its own specific parameters:
Note: The opensearch_url parameter listed under individual tools below is part of the common connection parameters described above. All common connection parameters (opensearch_username, opensearch_password, aws_region, etc.) are available on every tool but are not repeated in each tool's parameter list for brevity.
-
ListIndexTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (optional): The name of the index to get detailed information for. If provided, returns detailed information about this specific index instead of listing all indices.
-
IndexMappingTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (required): The name of the index to retrieve mappings for
-
SearchIndexTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (required): The name of the index to search inquery_dsl (required): The search query in OpenSearch Query DSL formatformat (optional): The format of SearchIndexTool response. options are csv and jsonsize (optional): The size of SearchIndexTool response. Default is 10, maximum is 100 (configurable). To change the maximum limit, set max_size_limit via CLI arguments or config file. See Tool Customization for details.
-
GetShardsTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (required): The name of the index to get shard information for
-
ClusterHealthTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (optional): Limit health reporting to a specific index
-
CountTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (optional): The name of the index to count documents inbody (optional): Query in JSON format to filter documents
-
ExplainTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (required): The name of the index to retrieve the document fromid (required): The document ID to explainbody (required): Query in JSON format to explain against the document
-
MsearchTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (optional): Default index to search inbody (required): Multi-search request body in NDJSON format
-
GetClusterStateTool
opensearch_url (optional): The OpenSearch cluster URL to connect tometric (optional): Limit the information returned to the specified metrics. Options include: _all, blocks, metadata, nodes, routing_table, routing_nodes, master_node, versionindex (optional): Limit the information returned to the specified indices
-
GetSegmentsTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (optional): Limit the information returned to the specified indices. If not provided, returns segments for all indices
-
CatNodesTool
opensearch_url (optional): The OpenSearch cluster URL to connect tometrics (optional): A comma-separated list of metrics to display. Available metrics include: id, name, ip, port, role, master, heap.percent, ram.percent, cpu, load_1m, load_5m, load_15m, disk.total, disk.used, disk.avail, disk.used_percent
-
GetNodesTool
opensearch_url (optional): The OpenSearch cluster URL to connect tonode_id (optional): A comma-separated list of node IDs or names to limit the returned information. Supports node filters like _local, _master, master:true, data:false, etc. Defaults to _all.metric (optional): A comma-separated list of metric groups to include in the response. Options include: settings, os, process, jvm, thread_pool, transport, http, plugins, ingest, aggregations, indices. Defaults to all metrics.
-
GetIndexInfoTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (required): The name of the index to get detailed information for. Wildcards are supported.
-
GetIndexStatsTool
opensearch_url (optional): The OpenSearch cluster URL to connect toindex (required): The name of the index to get statistics for. Wildcards are supported.metric (optional): Limit the information returned to the specified metrics. Options include: _all, completion, docs, fielddata, flush, get, indexing, merge, query_cache, refresh, request_cache, search, segments, store, warmer, bulk
-
GetQueryInsightsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
-
GetNodesHotThreadsTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
-
GetAllocationTool
opensearch_url (optional): The OpenSearch cluster URL to connect to
-
GetLongRunningTasksTool
opensearch_url (optional): The OpenSearch cluster URL to connect tolimit (optional): The maximum number of tasks to return. Default is 10.
-
CreateAgenticMemorySessionTool
memory_container_id (auto-populated): The ID of the memory container where the session will be created. Automatically set when configured via agentic_memory config or OPENSEARCH_MEMORY_CONTAINER_ID env var. (Path Parameter)session_id (optional): A custom session ID. If not provided, a random ID is generated. (Body Parameter)summary (optional): A session summary or description. (Body Parameter)metadata (optional): Additional metadata for the session provided as key-value pairs. (Body Parameter)namespace (optional): Namespace information for organizing the session. (Body Parameter)
-
AddAgenticMemoriesTool
memory_container_id (auto-populated): The ID of the memory container to add the memory to. Automatically set when configured. (Path Parameter)messages (conditional): A list of messages. Required when payload_type is conversational. (Body Parameter)structured_data (conditional): Structured data content. Required when payload_type is data. (Body Parameter)binary_data (optional): Binary data content encoded as a Base64 string for binary payloads. (Body Parameter)payload_type (required): The type of payload. Valid values are conversational or data. See Payload types. (Body Parameter)namespace (optional): The namespace context for organizing memories (for example, user_id, session_id, or agent_id). If session_id is not specified in the namespace field and disable_session: false (default is true), a new session with a new session ID is created. (Body Parameter)metadata (optional): Additional metadata for the memory (for example, status, branch, or custom fields). (Body Parameter)tags (optional): Tags for categorizing memories. (Body Parameter)infer (optional): Whether to use an LLM to extract key information (default: false). When true, the LLM extracts key information from the original text and stores it as a memory. See Inference mode. (Body Parameter)
-
GetAgenticMemoryTool
memory_container_id (auto-populated): The ID of the memory container from which to retrieve the memory. Automatically set when configured. (Path Parameter)type (required): The memory type. Valid values are sessions, working, long-term, and history. (Path Parameter)id (required): The ID of the memory to retrieve. (Path Parameter)
-
SearchAgenticMemoryTool
memory_container_id (auto-populated): The ID of the memory container. Automatically set when configured. (Path Parameter)type (required): The memory type. Valid values are sessions, working, long-term, and history. (Path Parameter)query (required): The search query using OpenSearch query DSL. (Body Parameter)sort (optional): Sort specification for the search results. (Body Parameter)
-
UpdateAgenticMemoryTool
memory_container_id (auto-populated): The ID of the memory container. Automatically set when configured. (Path Parameter)type (required): The memory type (sessions, working, or long-term).(Path Parameter)id (required): The ID of the memory to update.(Path Parameter)- Session memory request fields:
summary (optional): The summary of the session. (Body Parameter)metadata (optional): Additional metadata for the memory (for example, status, branch, or custom fields). (Body Parameter)agents (optional): Additional information about the agents. (Body Parameter)additional_info (optional): Additional metadata to associate with the session. (Body Parameter)
- Working memory request fields
messages (optional): Updated conversation messages (for conversation type). (Body Parameter)structured_data (optional): Updated structured data content (for data memory payloads). (Body Parameter)binary_data (optional): Updated binary data content (for data memory payloads). (Body Parameter)tags (optional): Updated tags for categorization. (Body Parameter)metadata (optional): Additional metadata for the memory (for example, status, branch, or custom fields). (Body Parameter)
- Long-term memory request fields
memory (optional): The updated memory content. (Body Parameter)tags (optional): Updated tags for categorization. (Body Parameter)
-
DeleteAgenticMemoryByIDTool
memory_container_id (auto-populated): The ID of the memory container from which to delete the memory. Automatically set when configured. (Path Parameter)type (required): The type of memory to delete. Valid values are sessions, working, long-term, and history. (Path Parameter)id (required): The ID of the specific memory to delete. (Path Parameter)
-
DeleteAgenticMemoryByQueryTool
memory_container_id (auto-populated): The ID of the memory container from which to delete the memory. Automatically set when configured. (Path Parameter)type (required): The type of memory to delete. Valid values are sessions, working, long-term, and history. (Path Parameter)query (required): The OpenSearch DSL query to match memories for deletion. (Body Parameter)
-
DataDistributionTool
index (required): Target OpenSearch index name.selectionTimeRangeStart (required): Start time for analysis target period.selectionTimeRangeEnd (required): End time for analysis target period.timeField (required): Date/time field for filtering.baselineTimeRangeStart (optional): Start time for baseline period.baselineTimeRangeEnd (optional): End time for baseline period.size (optional): Maximum number of documents to analyze. Default is 1000.
-
LogPatternAnalysisTool
index (required): Target OpenSearch index name containing log data.logFieldName (required): Field containing raw log messages to analyze.selectionTimeRangeStart (required): Start time for analysis target period.selectionTimeRangeEnd (required): End time for analysis target period.timeField (required): Date/time field for time-based filtering.traceFieldName (optional): Field for trace/correlation ID.baseTimeRangeStart (optional): Start time for baseline comparison period.baseTimeRangeEnd (optional): End time for baseline comparison period.
-
MetricChangeAnalysisTool
index (required): Target OpenSearch index name.selectionTimeRangeStart (required): Start of the selection (anomaly) period.selectionTimeRangeEnd (required): End of the selection (anomaly) period.baselineTimeRangeStart (required): Start of the baseline period.baselineTimeRangeEnd (required): End of the baseline period (should be at or before selectionTimeRangeStart).timeField (required): Date/time field for filtering.topN (optional): Number of top fields to return, ranked by change score. Default is 10.size (optional): Maximum number of documents to analyze. Default is 1000.
More tools coming soon. Click here
User Guide
For detailed usage instructions, configuration options, and examples, please see the User Guide.
Agent Memory
The OpenSearch MCP server includes two distinct memory systems. Both use OpenSearch as the storage backend but differ in who controls the memory lifecycle and what infrastructure they require.
Choosing the right approach
| Memory Tools (MEMORY_TOOLS_ENABLED) | Agentic Memory Tools (agentic_memory category) |
|---|
| Who stores memories | The MCP agent decides what to save as plain-text statements | OpenSearch processes raw conversations and extracts facts via LLM inference |
| Setup complexity | Low — index is auto-created on first use | High — requires creating a memory container with LLM connector and embedding model |
| OpenSearch version | Amazon OpenSearch Service 2.19+ or Serverless | OpenSearch 3.3.0+ |
| Semantic search | Yes, via AWS automatic semantic enrichment | Yes, via configured embedding model |
| Memory structure | Flat — each memory is a plain-text statement | Structured — sessions, working, long-term, and history types |
| LLM inference | No — agent writes exactly what it wants to remember | Optional (infer: true) — OpenSearch uses an LLM to extract facts from conversations |
| Best for | IDE agents (Kiro, Claude Code, Cursor) that need quick setup and cross-session continuity | Production agentic pipelines where memory management should be centralized and server-owned |
Use Memory Tools when you want a lightweight, agent-driven memory layer that works out of the box with any MCP-compatible IDE. The agent controls what gets remembered. See the Agent Memory Guide for setup.
Use Agentic Memory Tools when you want OpenSearch to own the full memory lifecycle — including LLM-based extraction of facts from raw conversations, structured memory types, and server-managed namespacing. See the Agent Memory Guide for setup.
Contributing
Interested in contributing? Check out our:
Code of Conduct
This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ, or contact opensource-codeofconduct@amazon.com with any additional questions or comments.
License
This project is licensed under the Apache v2.0 License.
Copyright
Copyright 2020-2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.