OpenSearch/Elasticsearch Connectivity Service for MCP

Introduction

This is a Model Context Protocol (MCP) server implementation dedicated to interfacing with Elasticsearch and OpenSearch environments. It empowers users to execute complex data operations, such as document retrieval, index analysis, and overall cluster administration, solely through descriptive, conversational commands.

Demonstration Video

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

Core Capabilities

Generic API Interaction

• general_api_request: Execute arbitrary HTTP requests against the Elasticsearch/OpenSearch REST interface. Recommended for endpoints lacking specialized tooling.

Index Management Tools

• list_indices: Enumerate all existing indices.
• get_index: Retrieve detailed metadata (schema, configurations, associated aliases) for specified indices.
• create_index: Provision a new index within the cluster.
• delete_index: Permanently remove a specified index.

Data Object Handling

• search_documents: Perform complex queries to locate data documents.
• index_document: Insert a new document or overwrite an existing one based on its ID.
• get_document: Fetch a specific document using its unique identifier.
• delete_document: Erase a document identified by its ID.
• delete_by_query: Mass deletion of documents that satisfy a given query predicate.

Cluster Status Monitoring

• get_cluster_health: Obtain the current operational status and high-level indicators of the cluster.
• get_cluster_stats: Access comprehensive statistics summarizing cluster performance and resource utilization.

Alias Administration

• list_aliases: Show all configured aliases.
• get_alias: Inspect the configuration of a particular alias.
• put_alias: Establish or modify an alias pointing to one or more indices.
• delete_alias: Remove an existing index alias association.

Environment Variable Configuration

Replicate the .env.example structure into a file named .env and populate the necessary connection parameters.

Cluster Initialization (Docker)

Deploy the required Elasticsearch or OpenSearch instance using Docker Compose:

bash

For Elasticsearch deployment

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

For OpenSearch deployment

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

Default credentials: Elasticsearch uses username elastic with password test123. OpenSearch uses username admin with password admin.

Access Kibana/OpenSearch Dashboards at http://localhost:5601.

Integration with Claude Desktop

Method 1: Automated Installation via Smithery

Install the server directly for use with Claude Desktop using the Smithery CLI:

bash npx -y @smithery/cli install elasticsearch-mcp-server --client claude

Method 2: Deployment using uvx (PyPI)

This method pulls the package directly from PyPI, avoiding local repository cloning. Integrate the following settings into your claude_desktop_config.json file:

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

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

Method 3: Local Development Setup with uv

If you have cloned the source code locally, use uv by pointing it to your source directory in claude_desktop_config.json:

// Configuration for Elasticsearch (Local Path) { "mcpServers": { "elasticsearch-mcp-server": { "command": "uv", "args": [ "--directory", "path/to/src/elasticsearch_mcp_server", "run", "elasticsearch-mcp-server" ], "env": { "ELASTICSEARCH_HOSTS": "https://localhost:9200", "ELASTICSEARCH_USERNAME": "elastic", "ELASTICSEARCH_PASSWORD": "test123" } } } }

// Configuration for OpenSearch (Local Path) { "mcpServers": { "opensearch-mcp-server": { "command": "uv", "args": [ "--directory", "path/to/src/elasticsearch_mcp_server", "run", "opensearch-mcp-server" ], "env": { "OPENSEARCH_HOSTS": "https://localhost:9200", "OPENSEARCH_USERNAME": "admin", "OPENSEARCH_PASSWORD": "admin" } } } }

Configuration file locations: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Remember to relaunch Claude Desktop for the new MCP server configuration to take effect.

Example natural language interactions: - "Enumerate all data collections in the cluster." - "What is the record for user 'Bob'?" - "Report the current operational status of the cluster."

Usage with Anthropic MCP Client

python uv run mcp_client/client.py src/server.py

Licensing Information

This software is distributed under the terms of the Apache License Version 2.0. Consult the LICENSE file for specifics.

Background Context: XMLHttpRequest (XHR)

XMLHttpRequest (XHR) defines an API implemented as a JavaScript object that facilitates the transmission of HTTP requests from a web browser to a remote server. This object's methods permit client-side applications to communicate with the server asynchronously following initial page load, enabling data exchange. XHR is fundamental to the structure of Ajax programming. Before its widespread adoption, server interaction heavily relied on traditional methods like link clicks and form submissions, which typically necessitated a full page refresh.

== Chronology == Microsoft's Outlook developers first conceptualized the underpinning technology in 2000. This concept was subsequently deployed within Internet Explorer 5 (released in 1999), although it initially utilized COM object identifiers such as ActiveXObject("Msxml2.XMLHTTP") instead of the standardized XMLHttpRequest name. By the release of Internet Explorer 7 (2006), universal support for the XMLHttpRequest identifier was achieved across major browser rendering engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A Level 2 specification followed on February 25, 2008, introducing enhancements like event progress monitoring, support for cross-site requests, and byte stream handling. By the close of 2011, the Level 2 features were incorporated back into the primary specification document. Development responsibility transitioned to the WHATWG near the end of 2012, which now maintains the living document using Web IDL notation.

== Operational Flow == Typically, invoking a server request via XMLHttpRequest involves several discrete programming stages:

1. Instantiation of the XMLHttpRequest object via its constructor.
2. Invoking the open() method to define the HTTP method, specify the target resource Uniform Resource Identifier (URI), and determine execution mode (synchronous or asynchronous).
3. For asynchronous operations, establishing an event handler to react to changes in the request's state.
4. Initiation of the actual transmission by calling the send() method.
5. Processing server responses by monitoring state transitions within the registered listener. Upon completion, the object reaches state 4 (the 'done' state), and the received data is generally accessible via the responseText property.

Beyond these fundamental steps, XHR offers extensive controls over request parameters and response handling. Custom HTTP headers can be appended to guide server processing. Payload data can be transferred to the server through the argument supplied to the send() call. Furthermore, responses can be automatically parsed from JSON into native JavaScript objects or streamed incrementally rather than awaiting the full payload arrival. The operation can also be canceled preemptively or configured to time out if not resolved within a set duration.

== Inter-Origin Communication == Early in the evolution of the World Wide Web, limitations were recognized regarding the ability to initiate requests to resources hosted on domains different from the origin site, leading to security restrictions.