Serveur MCP Elasticsearch Octodet

Serveur MCP Elasticsearch Octodet

Le serveur MCP Elasticsearch Octodet est un puissant serveur de Protocole de Contexte de Modèle (MCP) conçu pour une interaction fluide avec les clusters Elasticsearch. Il fournit un moyen standardisé pour les applications alimentées par LLM d'effectuer diverses opérations telles que la recherche, la mise à jour et la gestion des données au sein d'Elasticsearch.

Fonctionnalités

• Opérations Elasticsearch Complètes : Exécutez facilement des opérations CRUD complètes sur des documents et des indices.
• Opérations en Masse : Améliorez les performances en traitant plusieurs opérations dans un seul appel API.
• Mises à Jour/Suppressions Basées sur des Requêtes : Modifiez ou supprimez des documents en fonction de requêtes spécifiques.
• Gestion de Cluster : Surveillez la santé de votre cluster Elasticsearch, y compris les shards et les modèles.
• Recherche Avancée : Utilisez toutes les capacités des requêtes DSL d'Elasticsearch avec un support de mise en surbrillance intégré.

Comment Installer

En tant que Paquet NPM

Pour installer le serveur MCP Elasticsearch Octodet globalement, exécutez :

npm install -g @octodet/elasticsearch-mcp

Alternativement, vous pouvez l'utiliser directement avec npx :

npx @octodet/elasticsearch-mcp

À partir de la Source

1. Clonez le dépôt.
2. Installez les dépendances nécessaires :

npm install

3. Construisez le serveur :

npm run build

Intégration avec les Clients MCP

Intégration VS Code

Pour intégrer avec l'extension MCP de VS Code, ajoutez la configuration suivante à votre 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"
    }
  }
}

Intégration Claude Desktop

Pour Claude Desktop, configurez vos paramètres comme suit :

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

Pour le Développement Local

Si vous développez le serveur MCP localement, configurez vos clients pour utiliser votre build local :

{
  "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

Le serveur peut être configuré à l'aide des variables d'environnement suivantes :

| Variable | Description | Par défaut | | | | | | ES_URL | URL du serveur Elasticsearch | http://localhost:9200 | | ES_API_KEY | Clé API pour l'authentification | | | ES_USERNAME | Nom d'utilisateur pour l'authentification | | | ES_PASSWORD | Mot de passe pour l'authentification | | | ES_CA_CERT | Chemin vers le certificat CA personnalisé | | | ES_VERSION | Version d'Elasticsearch (8 ou 9) | 8 | | ES_SSL_SKIP_VERIFY | Ignorer la vérification SSL | false | | ES_PATH_PREFIX | Préfixe de chemin pour Elasticsearch | |

Outils

Le serveur comprend 16 outils MCP pour diverses opérations Elasticsearch, chacun documenté avec des paramètres requis et optionnels.

1. Lister les Indices

Récupérez une liste de tous les indices Elasticsearch disponibles avec des informations détaillées.

Paramètres :

• indexPattern (optionnel, chaîne) : Modèle pour filtrer les indices (par exemple, "logs-", "my-index-")

Exemple :

{
  "indexPattern": "logs-*"
}

2. Obtenir les Mappages

Récupérez les mappages de champs pour un indice Elasticsearch spécifique.

Paramètres :

• index (requis, chaîne) : Le nom de l'indice pour lequel récupérer les mappages.

Exemple :

{
  "index": "my-index"
}

3. Rechercher

Effectuez une recherche Elasticsearch en utilisant la requête DSL fournie et la mise en surbrillance.

Paramètres :

• index (requis, chaîne) : L'indice ou les indices à rechercher (prend en charge les valeurs séparées par des virgules).
• queryBody (requis, objet) : Le corps de la requête DSL d'Elasticsearch.
• highlight (optionnel, booléen) : Activer la mise en surbrillance pour les résultats de recherche (par défaut : vrai).

Exemple :

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

4. Obtenir la Santé du Cluster

Obtenez des informations sur la santé du cluster Elasticsearch.

Paramètres :

• Aucun requis.

Exemple :

{}

5. Obtenir les Shards

Récupérez des informations sur les shards pour tous les indices ou des indices spécifiques.

Paramètres :

• index (optionnel, chaîne) : Indice spécifique pour obtenir des informations sur les shards. Si omis, renvoie les shards pour tous les indices.

Exemple :

{
  "index": "my-index"
}

6. Ajouter un Document

Insérez un nouveau document dans un indice Elasticsearch spécifique.

Paramètres :

• index (requis, chaîne) : L'indice auquel le document sera ajouté.
• document (requis, objet) : Le contenu du document à ajouter.
• id (optionnel, chaîne) : ID du document. Si omis, Elasticsearch en génère un automatiquement.

Exemple :

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Mon Document",
    "content": "Contenu du document ici",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "brouillon"]
  }
}

7. Mettre à Jour un Document

Modifiez un document existant dans un indice Elasticsearch spécifique.

Paramètres :

• index (requis, chaîne) : L'indice contenant le document.
• id (requis, chaîne) : L'ID du document à mettre à jour.
• document (requis, objet) : Le document partiel avec les champs à mettre à jour.

Exemple :

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Titre du Document Mis à Jour",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Supprimer un Document

Supprimez un document d'un indice Elasticsearch spécifique.

Paramètres :

• index (requis, chaîne) : L'indice contenant le document.
• id (requis, chaîne) : L'ID du document à supprimer.

Exemple :

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

9. Mettre à Jour par Requête

Mettez à jour des documents dans un indice Elasticsearch en fonction d'une requête.

Paramètres :

• index (requis, chaîne) : L'indice pour mettre à jour les documents.
• query (requis, objet) : Requête Elasticsearch pour correspondre aux documents à mettre à jour.
• script (requis, objet) : Script à exécuter pour mettre à jour les documents correspondants.
• conflicts (optionnel, chaîne) : Comment gérer les conflits de version ("abort" ou "proceed", par défaut : "abort").
• refresh (optionnel, booléen) : Si l'index doit être rafraîchi après l'opération (par défaut : faux).

Exemple :

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

10. Supprimer par Requête

Supprimez des documents dans un indice Elasticsearch en fonction d'une requête.

Paramètres :

• index (requis, chaîne) : L'indice pour supprimer des documents.
• query (requis, objet) : Requête Elasticsearch pour correspondre aux documents à supprimer.
• conflicts (optionnel, chaîne) : Comment gérer les conflits de version ("abort" ou "proceed", par défaut : "abort").
• refresh (optionnel, booléen) : Si l'index doit être rafraîchi après l'opération (par défaut : faux).

Exemple :

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

11. Opérations en Masse

Exécutez plusieurs opérations de documents dans un seul appel API pour améliorer les performances.

Paramètres :

• operations (requis, tableau) : Tableau d'objets d'opération, chacun contenant :
  • action (requis, chaîne) : Le type d'opération ("index", "create", "update" ou "delete").
  • index (requis, chaîne) : L'indice pour cette opération.
  • id (optionnel, chaîne) : ID du document (requis pour mise à jour/suppression, optionnel pour indexation/création).
  • document (conditionnel, objet) : Contenu du document (requis pour les opérations d'indexation/création/mise à jour).

Exemple :

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Contenu ici" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Titre Mis à Jour" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Créer un Indice

Créez un nouvel indice Elasticsearch avec des paramètres et des mappages optionnels.

Paramètres :

• index (requis, chaîne) : Le nom de l'indice à créer.
• settings (optionnel, objet) : Paramètres de l'indice comme le nombre de shards, de répliques, etc.
• mappings (optionnel, objet) : Mappages de champs définissant comment les documents doivent être indexés.

Exemple :

{
  "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. Supprimer un Indice

Supprimez définitivement un indice Elasticsearch.

Paramètres :

• index (requis, chaîne) : Le nom de l'indice à supprimer.

Exemple :

{
  "index": "my-index"
}

14. Compter les Documents

Comptez les documents dans un indice, éventuellement filtrés par une requête.

Paramètres :

• index (requis, chaîne) : L'indice pour compter les documents.
• query (optionnel, objet) : Requête Elasticsearch pour filtrer les documents à compter.

Exemple :

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

15. Obtenir des Modèles

Récupérez des modèles d'index d'Elasticsearch.

Paramètres :

• name (optionnel, chaîne) : Nom spécifique du modèle à récupérer. Si omis, renvoie tous les modèles.

Exemple :

{
  "name": "logs-template"
}

16. Obtenir des Alias

Récupérez des alias d'index d'Elasticsearch.

Paramètres :

• name (optionnel, chaîne) : Nom spécifique de l'alias à récupérer. Si omis, renvoie tous les alias.

Exemple :

{
  "name": "logs-alias"
}

Développement

Exécution en Mode Développement

Pour exécuter le serveur en mode veille pendant le développement, utilisez :

npm run dev

Mise en Œuvre du Protocole

Ce serveur met en œuvre le Protocole de Contexte de Modèle pour faciliter la communication standardisée entre les clients LLM et Elasticsearch. Il fournit un ensemble complet d'outils pouvant être invoqués par les clients MCP pour effectuer diverses opérations Elasticsearch.

Ajout de Nouveaux Outils

Pour ajouter un nouvel outil au serveur :

1. Définissez l'outil dans src/index.ts en utilisant le format d'enregistrement d'outil du serveur MCP.
2. Implémentez la fonctionnalité nécessaire dans src/utils/elasticsearchService.ts.
3. Mettez à jour ce README pour documenter le nouvel outil.

Autres Clients MCP

Le serveur MCP Elasticsearch Octodet peut être utilisé avec tout client compatible MCP, y compris :

• ChatGPT d'OpenAI via des plugins MCP
• Claude Desktop d'Anthropic
• Claude dans VS Code
• Applications personnalisées utilisant le SDK MCP

Utilisation Programmatique

Vous pouvez également utiliser le serveur de manière programmatique dans vos applications Node.js :

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

// Configurez la connexion Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Créez et démarrez le serveur
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connectez-vous à votre transport personnalisé
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Serveur MCP Elasticsearch démarré");
}

startServer().catch(console.error);

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour les détails.

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.

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:

npm install -g @octodet/elasticsearch-mcp

Or use it directly with npx:

npx @octodet/elasticsearch-mcp

From Source

1. Clone this repository
2. Install dependencies:

npm install

3. Build the server:

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:

"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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{}

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

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:

{
  "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

Delete an Elasticsearch index permanently.

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

Get 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

Get 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

Run the server in watch mode during development:

npm run dev

Protocol Implementation

This server implements the Model Context Protocol 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:

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.