elastic · jedrazb · Mar 28, 2025 · Mar 27, 2025 · Mar 27, 2025 · Mar 28, 2025
@@ -2,7 +2,7 @@
 
 Connect to your Elasticsearch data directly from any MCP Client (like Claude Desktop) using the Model Context Protocol (MCP).
 
-This server connects agents to your Elasticsearch data using the Model Context Protocol (MCP). It allows you to interact with your Elasticsearch indices through natural language conversations.
+This server connects agents to your Elasticsearch data using the Model Context Protocol. It allows you to interact with your Elasticsearch indices through natural language conversations.
 
 ## Features
 
@@ -12,115 +12,134 @@ This server connects agents to your Elasticsearch data using the Model Context P
 
 ## Prerequisites
 
-* Node.js (v22+)
 * An Elasticsearch instance
 * Elasticsearch API key with appropriate permissions
-* Claude Desktop App (free version is sufficient)
+* MCP Client (e.g. Claude Desktop)
+
+## Demo
+
+https://github.com/user-attachments/assets/5dd292e1-a728-4ca7-8f01-1380d1bebe0c
 
 ## Installation & Setup
 
 ### Using the Published NPM Package
 
-The easiest way to use Elasticsearch MCP Server is through the published npm package:
+> [!TIP]
+> The easiest way to use Elasticsearch MCP Server is through the published npm package.
 
-1. **Configure Claude Desktop App**
-   - Open Claude Desktop App
-   - Go to Settings > Developer > MCP Servers
-   - Click `Edit Config` and add a new MCP Server with the following configuration to your `claude_desktop_config.json`:
+1. **Configure MCP Client**
+   - Open your MCP Client. See the [list of MCP Clients](https://modelcontextprotocol.io/clients), here we are configuring Claude Desktop.
+   - Go to **Settings > Developer > MCP Servers**
+   - Click `Edit Config` and add a new MCP Server with the following configuration:
 
-```json
-{
-  "mcpServers": {
-    "elasticsearch-mcp-server": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@elastic/mcp-server-elasticsearch"
-      ],
-      "env": {
-        "ES_URL": "your-elasticsearch-url",
-        "ES_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
+   ```json
+   {
+     "mcpServers": {
+       "elasticsearch-mcp-server": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "@elastic/mcp-server-elasticsearch"
+         ],
+         "env": {
+           "ES_URL": "your-elasticsearch-url",
+           "ES_API_KEY": "your-api-key"
+         }
+       }
+     }
+   }
+   ```
 
 2. **Start a Conversation**
-   - Open a new conversation in Claude Desktop App
+   - Open a new conversation in your MCP Client
    - The MCP server should connect automatically
-   - You can now ask Claude questions about your Elasticsearch data
+   - You can now ask questions about your Elasticsearch data
 
 ### Developing Locally
 
-If you want to develop or modify the server locally:
+> [!NOTE]
+> If you want to modify or extend the MCP Server, follow these local development steps.
 
 1. **Use the correct Node.js version**
-```bash
-nvm use
-```
+   ```bash
+   nvm use
+   ```
 
 2. **Install Dependencies**
-```bash
-npm install
-```
+   ```bash
+   npm install
+   ```
 
 3. **Build the Project**
-```bash
-npm run build
-```
+   ```bash
+   npm run build
+   ```
 
-4. **Configure Claude Desktop for local development**
-   - Open Claude Desktop App
-   - Go to Settings > Developer > MCP Servers
+4. **Run locally in Claude Desktop App**
+   - Open **Claude Desktop App**
+   - Go to **Settings > Developer > MCP Servers**
    - Click `Edit Config` and add a new MCP Server with the following configuration:
 
-```json
-{
-  "mcpServers": {
-    "Elasticsearch MCP Server (Local)": {
-      "command": "node",
-      "args": [
-        "/path/to/your/project/dist/index.js"
-      ],
-      "env": {
-        "ES_URL": "your-elasticsearch-url",
-        "ES_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-5. **Debugging**
-```bash
-npm run inspector
-```
+   ```json
+   {
+     "mcpServers": {
+       "elasticsearch-mcp-server-local": {
+         "command": "node",
+         "args": [
+           "/path/to/your/project/dist/index.js"
+         ],
+         "env": {
+           "ES_URL": "your-elasticsearch-url",
+           "ES_API_KEY": "your-api-key"
+         }
+       }
+     }
+   }
+   ```
+
+5. **Debugging with MCP Inspector**
+   ```bash
+   ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector
+   ```
+
+   This will start the MCP Inspector, allowing you to debug and analyze requests. Ensure that the necessary environment variables (`ES_URL` and `ES_API_KEY`) are exposed when starting the inspector. You should see output similar to:
+
+   ```bash
+   Starting MCP inspector...
+   Proxy server listening on port 3000
+
+   🔍 MCP Inspector is up and running at http://localhost:5173 🚀
+   ```
 
 ## Example Questions
 
+> [!TIP]
+> Here are some natural language queries you can try with your MCP Client.
+
 * "What indices do I have in my Elasticsearch cluster?"
-* "Show me the field mappings for the 'products' index"
-* "Find all orders over $500 from last month"
+* "Show me the field mappings for the 'products' index."
+* "Find all orders over $500 from last month."
 * "Which products received the most 5-star reviews?"
 
 ## How It Works
 
-When you ask Claude a question about your data:
-1. Claude analyzes your request and determines which Elasticsearch operations are needed
-2. The MCP server carries out these operations (listing indices, fetching mappings, performing searches)
-3. Claude processes the results and presents them in a user-friendly format
+1. The MCP Client analyzes your request and determines which Elasticsearch operations are needed.
+2. The MCP server carries out these operations (listing indices, fetching mappings, performing searches).
+3. The MCP Client processes the results and presents them in a user-friendly format.
 
 ## Security Best Practices
 
+> [!WARNING]
+> Avoid using cluster-admin privileges. Create dedicated API keys with limited scope and apply fine-grained access control at the index level to prevent unauthorized data access.
+
 You can create a dedicated Elasticsearch API key with minimal permissions to control access to your data:
 
 ```
 POST /_security/api_key
 {
   "name": "es-mcp-server-access",
   "role_descriptors": {
-    "claude_role": {
+    "mcp_server_role": {
       "cluster": [
         "monitor"
       ],
@@ -144,7 +163,10 @@ POST /_security/api_key
 
 ## Troubleshooting
 
-* If the server isn't connecting, check that your MCP configuration is correct
-* Ensure your Elasticsearch URL is accessible from your machine
-* Verify that your API key has the necessary permissions
-* Check the terminal output for any error messages
+
+* Ensure your MCP configuration is correct.
+* Verify that your Elasticsearch URL is accessible from your machine.
+* Check that your API key has the necessary permissions.
+* Look at the terminal output for error messages.
+
+If you encounter issues, feel free to open an issue on the GitHub repository.