Octodet Elasticsearch MCP Server

The Octodet Elasticsearch MCP Server is a robust Model Context Protocol (MCP) server designed for smooth interaction with Elasticsearch clusters. It offers a standardized method for LLM-powered applications to carry out various tasks such as searching, updating, and managing data within Elasticsearch.

Features

Complete Elasticsearch Operations: Effortlessly execute full CRUD operations on documents and indices.
Bulk Operations: Improve performance by processing multiple operations in a single API call.
Query-Based Updates/Deletes: Change or remove documents based on specific queries.
Cluster Management: Keep track of the health of your Elasticsearch cluster, including shards and templates.
Advanced Search: Leverage the full capabilities of Elasticsearch DSL queries with built-in highlighting support.

How to Install

As an NPM Package

To install the Octodet Elasticsearch MCP Server globally, run:

npm install -g @octodet/elasticsearch-mcp

Alternatively, you can use it directly with npx:

npx @octodet/elasticsearch-mcp

From Source

Clone the repository.
Install the necessary dependencies:

npm install

Build the server:

npm run build

Integration with MCP Clients

VS Code Integration

To integrate with the VS Code MCP extension, add the following configuration to your settings.json:

"mcp.servers": {
  "elasticsearch": {
    "command": "npx",
    "args": [
      "-y", "@octodet/elasticsearch-mcp"
    ],
    "env": {
      "ES_URL": "http://localhost:9200",
      "ES_API_KEY": "your_api_key",
      "ES_VERSION": "8"
    }
  }
}

Claude Desktop Integration

For Claude Desktop, configure your settings as follows:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@octodet/elasticsearch-mcp"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

For Local Development

If you are developing the MCP server locally, configure your clients to use your local build:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["path/to/build/index.js"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "your_api_key",
        "ES_VERSION": "8"
      }
    }
  }
}

Configuration

The server can be configured using the following environment variables:

Variable	Description	Default
ES_URL	Elasticsearch server URL	http://localhost:9200
ES_API_KEY	API key for authentication
ES_USERNAME	Username for authentication
ES_PASSWORD	Password for authentication
ES_CA_CERT	Path to custom CA certificate
ES_VERSION	Elasticsearch version (8 or 9)	8
ES_SSL_SKIP_VERIFY	Skip SSL verification	false
ES_PATH_PREFIX	Path prefix for Elasticsearch

Tools

The server includes 16 MCP tools for various Elasticsearch operations, each documented with required and optional parameters.

1. List Indices

Retrieve a list of all available Elasticsearch indices with detailed information.

Parameters:

indexPattern (optional, string): Pattern to filter indices (e.g., "logs-", "my-index-")

Example:

{
  "indexPattern": "logs-*"
}

2. Get Mappings

Fetch field mappings for a specific Elasticsearch index.

Parameters:

index (required, string): The name of the index to retrieve mappings for.

Example:

{
  "index": "my-index"
}

3. Search

Conduct an Elasticsearch search using the provided query DSL and highlighting.

Parameters:

index (required, string): The index or indices to search in (supports comma-separated values).
queryBody (required, object): The Elasticsearch query DSL body.
highlight (optional, boolean): Enable highlighting for search results (default: true).

Example:

{
  "index": "my-index",
  "queryBody": {
    "query": {
      "match": {
        "content": "search term"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Get Cluster Health

Obtain health information about the Elasticsearch cluster.

Parameters:

None required.

Example:

{}

5. Get Shards

Retrieve shard information for all or specific indices.

Parameters:

index (optional, string): Specific index to get shard information for. If omitted, returns shards for all indices.

Example:

{
  "index": "my-index"
}

6. Add Document

Insert a new document into a specific Elasticsearch index.

Parameters:

index (required, string): The index to which the document will be added.
document (required, object): The content of the document to add.
id (optional, string): Document ID. If omitted, Elasticsearch generates one automatically.

Example:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "My Document",
    "content": "Document content here",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "draft"]
  }
}

7. Update Document

Modify an existing document in a specific Elasticsearch index.

Parameters:

index (required, string): The index containing the document.
id (required, string): The ID of the document to update.
document (required, object): The partial document with fields to update.

Example:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Updated Document Title",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Delete Document

Remove a document from a specific Elasticsearch index.

Parameters:

index (required, string): The index containing the document.
id (required, string): The ID of the document to delete.

Example:

{
  "index": "my-index",
  "id": "doc1"
}

9. Update By Query

Update documents in an Elasticsearch index based on a query.

Parameters:

index (required, string): The index to update documents in.
query (required, object): Elasticsearch query to match documents for update.
script (required, object): Script to execute for updating matched documents.
conflicts (optional, string): How to handle version conflicts ("abort" or "proceed", default: "abort").
refresh (optional, boolean): Whether to refresh the index after the operation (default: false).

Example:

{
  "index": "my-index",
  "query": {
    "term": {
      "status": "active"
    }
  },
  "script": {
    "source": "ctx._source.status = params.newStatus; ctx._source.updated_at = params.timestamp",
    "params": {
      "newStatus": "inactive",
      "timestamp": "2025-06-23T10:30:00Z"
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

10. Delete By Query

Delete documents in an Elasticsearch index based on a query.

Parameters:

index (required, string): The index to delete documents from.
query (required, object): Elasticsearch query to match documents for deletion.
conflicts (optional, string): How to handle version conflicts ("abort" or "proceed", default: "abort").
refresh (optional, boolean): Whether to refresh the index after the operation (default: false).

Example:

{
  "index": "my-index",
  "query": {
    "range": {
      "created_date": {
        "lt": "2025-01-01"
      }
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

11. Bulk Operations

Execute multiple document operations in a single API call for improved performance.

Parameters:

operations (required, array): Array of operation objects, each containing:
- action (required, string): The operation type ("index", "create", "update", or "delete").
- index (required, string): The index for this operation.
- id (optional, string): Document ID (required for update/delete, optional for index/create).
- document (conditional, object): Document content (required for index/create/update operations).

Example:

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Content here" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Updated Title" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Create Index

Create a new Elasticsearch index with optional settings and mappings.

Parameters:

index (required, string): The name of the index to create.
settings (optional, object): Index settings like number of shards, replicas, etc.
mappings (optional, object): Field mappings defining how documents should be indexed.

Example:

{
  "index": "new-index",
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "analysis": {
      "analyzer": {
        "custom_analyzer": {
          "type": "standard",
          "stopwords": "_english_"
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "custom_analyzer"
      },
      "created": {
        "type": "date",
        "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
      },
      "tags": {
        "type": "keyword"
      }
    }
  }
}

13. Delete Index

Permanently delete an Elasticsearch index.

Parameters:

index (required, string): The name of the index to delete.

Example:

{
  "index": "my-index"
}

14. Count Documents

Count documents in an index, optionally filtered by a query.

Parameters:

index (required, string): The index to count documents in.
query (optional, object): Elasticsearch query to filter documents for counting.

Example:

{
  "index": "my-index",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "active" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. Get Templates

Retrieve index templates from Elasticsearch.

Parameters:

name (optional, string): Specific template name to retrieve. If omitted, returns all templates.

Example:

{
  "name": "logs-template"
}

16. Get Aliases

Fetch index aliases from Elasticsearch.

Parameters:

name (optional, string): Specific alias name to retrieve. If omitted, returns all aliases.

Example:

{
  "name": "logs-alias"
}

Development

Running in Development Mode

To run the server in watch mode during development, use:

npm run dev

Protocol Implementation

This server implements the Model Context Protocol to facilitate standardized communication between LLM clients and Elasticsearch. It provides a comprehensive set of tools that can be invoked by MCP clients to perform various Elasticsearch operations.

Adding New Tools

To add a new tool to the server:

Define the tool in src/index.ts using the MCP server's tool registration format.
Implement the necessary functionality in src/utils/elasticsearchService.ts.
Update this README to document the new tool.

Other MCP Clients

The Octodet Elasticsearch MCP Server can be utilized with any MCP-compatible client, including:

OpenAI's ChatGPT via MCP plugins
Anthropic's Claude Desktop
Claude in VS Code
Custom applications using the MCP SDK

Programmatic Usage

You can also use the server programmatically in your Node.js applications:

import { createOctodetElasticsearchMcpServer } from "@octodet/elasticsearch-mcp";
import { CustomTransport } from "@modelcontextprotocol/sdk/server";

// Configure the Elasticsearch connection
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Create and start the server
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connect to your custom transport
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Elasticsearch MCP server started");
}

startServer().catch(console.error);

License

This project is licensed under the MIT License - see the LICENSE file for details.

Octodet Elasticsearch MCP Server

Overview