Managed Context Provider for Search Engines (Elasticsearch/OpenSearch)

Registry Reference

Synopsis

This Model Context Protocol (MCP) endpoint furnishes capabilities for interfacing with both Elasticsearch and OpenSearch environments. It exposes a suite of utilities allowing users to execute data queries, manipulate index definitions, and query the operational status of the cluster.

Demonstration

Link to sample usage: https://github.com/user-attachments/assets/f7409e31-fac4-4321-9c94-b0ff2ea7ff15

Core Toolset

Generic Endpoint Access

• general_api_request: Execute arbitrary HTTP requests against the underlying search engine API. Recommended for functionalities not covered by specific tools.

Index Administration

• list_indices: Enumerate all existing indexes.
• get_index: Retrieve detailed configuration (schema, settings, aliases) for specified indexes.
• create_index: Provision a new index.
• delete_index: Remove an existing index.
• create_data_stream: Set up a new data stream (requires prior template definition).
• get_data_stream: Query metadata for one or more data streams.
• delete_data_stream: Erase data streams along with their constituent backing indices.

Document Manipulation

• search_documents: Execute searches against indexed documents based on query criteria.
• index_document: Insert a new document or overwrite an existing one using its identifier.
• get_document: Fetch a single document via its unique ID.
• delete_document: Remove a document based on its ID.
• delete_by_query: Purge documents matching a specified query predicate.

Cluster Status

• get_cluster_health: Obtain a summary of the cluster's operational status.
• get_cluster_stats: Retrieve aggregate performance and usage statistics for the cluster.

Alias Management

• list_aliases: List all defined aliases.
• get_alias: Inspect the configuration of a particular alias.
• put_alias: Associate or re-point an alias to a different index.
• delete_alias: Decommission an alias.

Configuration via Environment Variables

The server initialization utilizes the following environment variables for security and connection parameters:

Credential Handling (Username/Password)

• ELASTICSEARCH_USERNAME: Credential for Basic Auth on Elasticsearch.
• ELASTICSEARCH_PASSWORD: Secret for Basic Auth on Elasticsearch.
• OPENSEARCH_USERNAME: Credential for Basic Auth on OpenSearch.
• OPENSEARCH_PASSWORD: Secret for Basic Auth on OpenSearch.

API Key Mode (Elasticsearch Recommended)

• ELASTICSEARCH_API_KEY: Token for secure access to Elasticsearch or Elastic Cloud deployments.

Connection Parameters

• ELASTICSEARCH_HOSTS / OPENSEARCH_HOSTS: A comma-separated collection of endpoint URLs (Default: https://localhost:9200).
• ELASTICSEARCH_VERIFY_CERTS / OPENSEARCH_VERIFY_CERTS: Boolean flag to control SSL certificate validation (Default: false).

Initializing the Search Engine Cluster

Use Docker Compose scripts to launch the necessary backend infrastructure:

bash

Deploy Elasticsearch instance

docker-compose -f docker-compose-elasticsearch.yml up -d

Deploy OpenSearch instance

docker-compose -f docker-compose-opensearch.yml up -d

Default credentials: Elasticsearch uses user elastic with password test123. OpenSearch uses user admin with password admin. Access the graphical interface via http://localhost:5601 (Kibana/Dashboards).

Execution via Stdio

Method A: Using uvx (Installation from PyPI)

This approach bypasses local cloning, fetching the package automatically. Configure your claude_desktop_config.json as follows:

// For Elasticsearch with credentials { "mcpServers": { "elasticsearch-mcp-server": { "command": "uvx", "args": [ "elasticsearch-mcp-server" ], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_USERNAME": "elastic", "ELASTICSEARCH_PASSWORD": "test123" } } } }

// For Elasticsearch utilizing an API key { "mcpServers": { "elasticsearch-mcp-server": { "command": "uvx", "args": [ "elasticsearch-mcp-server" ], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "" } } } }

// For OpenSearch deployment { "mcpServers": { "opensearch-mcp-server": { "command": "uvx", "args": [ "opensearch-mcp-server" ], "env": { "OPENSEARCH_HOSTS": "https://localhost:9200", "OPENSEARCH_USERNAME": "admin", "OPENSEARCH_PASSWORD": "admin" } } } }

Method B: Local Development with uv

Requires cloning the repository and pointing to the source directory in your configuration file claude_desktop_config.json.

// For Elasticsearch with credentials { "mcpServers": { "elasticsearch-mcp-server": { "command": "uv", "args": [ "--directory", "path/to/elasticsearch-mcp-server", "run", "elasticsearch-mcp-server" ], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_USERNAME": "elastic", "ELASTICSEARCH_PASSWORD": "test123" } } } }

// For Elasticsearch utilizing an API key { "mcpServers": { "elasticsearch-mcp-server": { "command": "uv", "args": [ "--directory", "path/to/elasticsearch-mcp-server", "run", "elasticsearch-mcp-server" ], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_API_KEY": "" } } } }

// For OpenSearch deployment { "mcpServers": { "opensearch-mcp-server": { "command": "uv", "args": [ "--directory", "path/to/elasticsearch-mcp-server", "run", "opensearch-mcp-server" ], "env": { "OPENSEARCH_HOSTS": "https://localhost:9200", "OPENSEARCH_USERNAME": "admin", "OPENSEARCH_PASSWORD": "admin" } } } }

Server-Sent Events (SSE) Transport

Method A: Using uvx

bash

Set environment variables (e.g., Basic Auth)

export ELASTICSEARCH_HOSTS="https://localhost:9200" export ELASTICSEARCH_USERNAME="elastic" export ELASTICSEARCH_PASSWORD="test123"

OR using API Key

export ELASTICSEARCH_HOSTS="https://localhost:9200" export ELASTICSEARCH_API_KEY=""

Launch server (Default endpoint: http://127.0.0.1:8000/sse)

uvx elasticsearch-mcp-server --transport sse

Customize host/port/path

uvx elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Method B: Using uv

bash

Launch server (Default endpoint: http://127.0.0.1:8000/sse)

uv run src/server.py elasticsearch-mcp-server --transport sse

Customize host/port/path

uv run src/server.py elasticsearch-mcp-server --transport sse --host 0.0.0.0 --port 8000 --path /sse

Streamable HTTP Transport

Method A: Using uvx

bash

Set environment variables (e.g., Basic Auth)

export ELASTICSEARCH_HOSTS="https://localhost:9200" export ELASTICSEARCH_USERNAME="elastic" export ELASTICSEARCH_PASSWORD="test123"

OR using API Key

export ELASTICSEARCH_HOSTS="https://localhost:9200" export ELASTICSEARCH_API_KEY=""

Launch server (Default endpoint: http://127.0.0.1:8000/mcp)

uvx elasticsearch-mcp-server --transport streamable-http

Customize host/port/path

uvx elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Method B: Using uv

bash

Launch server (Default endpoint: http://127.0.0.1:8000/mcp)

uv run src/server.py elasticsearch-mcp-server --transport streamable-http

Customize host/port/path

uv run src/server.py elasticsearch-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Version Compatibility

The server package supports connectivity across Elasticsearch versions 7.x, 8.x, and 9.x. The default configuration utilizes the Elasticsearch 8.x client library.

MCP Variant	Target Elasticsearch Version
elasticsearch-mcp-server-es7	Elasticsearch 7.x
elasticsearch-mcp-server	Elasticsearch 8.x (Default)
elasticsearch-mcp-server-es9	Elasticsearch 9.x
opensearch-mcp-server	OpenSearch 1.x, 2.x, 3.x

To invoke the 7.x compatible client, execute the elasticsearch-mcp-server-es7 variant, e.g., uvx elasticsearch-mcp-server-es7. Use elasticsearch-mcp-server-es9 for version 9.x.

If compiling variants (like ES 7.x or 9.x) locally, adjust the dependency specification in pyproject.toml before launching via:

bash uv run src/server.py elasticsearch-mcp-server

Licensing

This software is distributed under the terms of the Apache License Version 2.0. Review the LICENSE file for full legal text.

== Background on Asynchronous HTTP Requests ==

XMLHttpRequest (XHR) is a fundamental JavaScript API structured as a callable object that allows client-side scripts to dispatch HTTP requests to a web server dynamically. This capability permits web applications to fetch or transmit data following the initial page load, forming the backbone of AJAX programming. Before XHR, server interaction typically mandated full page refreshes initiated by form submissions or standard hyperlinks.

=== Genesis ===

The conceptual foundation for asynchronous communication was pioneered in 2000 by the Microsoft Outlook development team. This concept first materialized in Internet Explorer 5 (released in 1999). Note that the initial implementation did not use the standardized XMLHttpRequest object name; instead, it relied on COM object instantiations such as ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 arrived in 2006, unified support for the standard XMLHttpRequest identifier was established across the browser landscape, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts ===

The World Wide Web Consortium (W3C) formalized the interface by publishing a Working Draft specification for the XHR object in April 2006. A subsequent Level 2 specification, enhancing progress monitoring, enabling cross-site communication, and supporting byte stream handling, appeared in February 2008. The Level 2 enhancements were eventually merged back into the primary specification by late 2011. Development responsibilities transitioned to WHATWG near the close of 2012, which now maintains the living standard documented using Web IDL.

== Operational Steps ==

Typically, initiating a request using XHR involves a sequence of programming operations:

1. Instantiation: Create a new XMLHttpRequest object instance via its constructor.
2. Configuration: Invoke the open() method to define the request method (GET, POST, etc.), specify the target URI, and determine whether the operation will proceed synchronously or asynchronously.
3. Event Handling (Async Only): For asynchronous calls, register a handler function to be triggered upon changes in the request's state.
4. Transmission: Start the network transaction by calling the send() method, optionally including payload data.
5. Response Processing: Monitor the state changes within the assigned listener. Upon completion, if data is returned, it is typically accessible via the responseText property when the state reaches 4 (the 'done' state).

Beyond these core steps, XHR offers finer control: custom HTTP headers can be added to influence server behavior, data can be uploaded incrementally, responses can be parsed directly from JSON structures, and requests can be automatically terminated if they exceed a set timeout limit or need to be canceled preemptively.