README.md•12.7 kB
# Octodet Elasticsearch MCP Server
A Model Context Protocol (MCP) server for Elasticsearch operations, providing a comprehensive set of tools for interacting with Elasticsearch clusters through the standardized Model Context Protocol. This server enables LLM-powered applications to search, update, and manage Elasticsearch data.
<a href="https://glama.ai/mcp/servers/@Octodet/elasticsearch-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@Octodet/elasticsearch-mcp/badge" alt="octodet-elasticsearch-mcp MCP server" />
</a>
## Features
- **Complete Elasticsearch Operations**: Full CRUD operations for documents and indices
- **Bulk Operations**: Process multiple operations in a single API call
- **Query-Based Updates/Deletes**: Modify or remove documents based on queries
- **Cluster Management**: Monitor health, shards, and templates
- **Advanced Search**: Full support for Elasticsearch DSL queries with highlighting
## Installation
### As an NPM Package
Install the package globally:
```bash
npm install -g @octodet/elasticsearch-mcp
```
Or use it directly with npx:
```bash
npx @octodet/elasticsearch-mcp
```
### From Source
1. Clone this repository
2. Install dependencies:
```bash
npm install
```
3. Build the server:
```bash
npm run build
```
## Integration with MCP Clients
### VS Code Integration
Add the following configuration to your VS Code settings.json to integrate with the VS Code MCP extension:
```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
Configure in your Claude Desktop configuration file:
```json
{
"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're developing the MCP server locally, you can configure the clients to use your local build:
```json
{
"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 uses the following environment variables for configuration:
| 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 provides 16 MCP tools for Elasticsearch operations. Each tool is documented with its required and optional parameters:
### 1. List Indices
List all available Elasticsearch indices with detailed information.
**Parameters:**
- `indexPattern` (optional, string): Pattern to filter indices (e.g., "logs-_", "my-index-_")
**Example:**
```json
{
"indexPattern": "logs-*"
}
```
### 2. Get Mappings
Get field mappings for a specific Elasticsearch index.
**Parameters:**
- `index` (required, string): The name of the index to get mappings for
**Example:**
```json
{
"index": "my-index"
}
```
### 3. Search
Perform an Elasticsearch search with 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 search result highlighting (default: true)
**Example:**
```json
{
"index": "my-index",
"queryBody": {
"query": {
"match": {
"content": "search term"
}
},
"size": 10,
"from": 0,
"sort": [{ "_score": { "order": "desc" } }]
},
"highlight": true
}
```
### 4. Get Cluster Health
Get health information about the Elasticsearch cluster.
**Parameters:**
- None required
**Example:**
```json
{}
```
### 5. Get Shards
Get 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:**
```json
{
"index": "my-index"
}
```
### 6. Add Document
Add a new document to a specific Elasticsearch index.
**Parameters:**
- `index` (required, string): The index to add the document to
- `document` (required, object): The document content to add
- `id` (optional, string): Document ID. If omitted, Elasticsearch will generate one automatically
**Example:**
```json
{
"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
Update 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:**
```json
{
"index": "my-index",
"id": "doc1",
"document": {
"title": "Updated Document Title",
"last_modified": "2025-06-23T10:30:00Z"
}
}
```
### 8. Delete Document
Delete 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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"index": "my-index",
"query": {
"range": {
"created_date": {
"lt": "2025-01-01"
}
}
},
"conflicts": "proceed",
"refresh": true
}
```
### 11. Bulk Operations
Perform multiple document operations in a single API call for better 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:**
```json
{
"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:**
```json
{
"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
Delete an Elasticsearch index permanently.
**Parameters:**
- `index` (required, string): The name of the index to delete
**Example:**
```json
{
"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:**
```json
{
"index": "my-index",
"query": {
"bool": {
"must": [
{ "term": { "status": "active" } },
{ "range": { "created_date": { "gte": "2025-01-01" } } }
]
}
}
}
```
### 15. Get Templates
Get index templates from Elasticsearch.
**Parameters:**
- `name` (optional, string): Specific template name to retrieve. If omitted, returns all templates
**Example:**
```json
{
"name": "logs-template"
}
```
### 16. Get Aliases
Get index aliases from Elasticsearch.
**Parameters:**
- `name` (optional, string): Specific alias name to retrieve. If omitted, returns all aliases
**Example:**
```json
{
"name": "logs-alias"
}
```
## Development
### Running in Development Mode
Run the server in watch mode during development:
```bash
npm run dev
```
### Protocol Implementation
This server implements the [Model Context Protocol](https://github.com/modelcontextprotocol/modelcontextprotocol) to enable standardized communication between LLM clients and Elasticsearch. It provides a 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:
1. Define the tool in `src/index.ts` using the MCP server's tool registration format
2. Implement the necessary functionality in `src/utils/elasticsearchService.ts`
3. Update this README to document the new tool
## Other MCP Clients
This server can be used 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:
```javascript
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](LICENSE) file for details.