Octodet Elasticsearch MCP 服务器

创建者

Octodet•Jun 25, 2025

一个完整的 Elasticsearch MCP 服务器

概览

Octodet Elasticsearch MCP 服务器

Octodet Elasticsearch MCP 服务器是一个强大的模型上下文协议（MCP）服务器，旨在与 Elasticsearch 集群无缝交互。它为基于 LLM 的应用程序提供了一种标准化的方式，以在 Elasticsearch 中执行各种操作，如搜索、更新和管理数据。

特性

完整的 Elasticsearch 操作：轻松执行文档和索引的完整 CRUD 操作。
批量操作：通过在单个 API 调用中处理多个操作来提高性能。
基于查询的更新/删除：根据特定查询修改或删除文档。
集群管理：监控 Elasticsearch 集群的健康状况，包括分片和模板。
高级搜索：利用 Elasticsearch DSL 查询的全部功能，并支持内置高亮。

如何安装

作为 NPM 包

要全局安装 Octodet Elasticsearch MCP 服务器，请运行：

npm install -g @octodet/elasticsearch-mcp

或者，您可以直接使用 npx：

npx @octodet/elasticsearch-mcp

从源代码

克隆代码库。
安装必要的依赖项：

npm install

构建服务器：

npm run build

与 MCP 客户端的集成

VS Code 集成

要与 VS Code MCP 扩展集成，请将以下配置添加到您的 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 集成

对于 Claude Desktop，请按如下方式配置您的设置：

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

本地开发

如果您在本地开发 MCP 服务器，请配置您的客户端以使用本地构建：

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

配置

服务器可以使用以下环境变量进行配置：

工具

服务器包括 16 个用于各种 Elasticsearch 操作的 MCP 工具，每个工具都有所需和可选参数的文档。

1. 列出索引

检索所有可用 Elasticsearch 索引的详细信息。

参数：

indexPattern（可选，字符串）：用于过滤索引的模式（例如，“logs-”，“my-index-”）

示例：

{
  "indexPattern": "logs-*"
}

2. 获取映射

获取特定 Elasticsearch 索引的字段映射。

参数：

index（必需，字符串）：要检索映射的索引名称。

示例：

{
  "index": "my-index"
}

3. 搜索

使用提供的查询 DSL 和高亮进行 Elasticsearch 搜索。

参数：

index（必需，字符串）：要搜索的索引或索引（支持以逗号分隔的值）。
queryBody（必需，对象）：Elasticsearch 查询 DSL 主体。
highlight（可选，布尔值）：是否为搜索结果启用高亮（默认：true）。

示例：

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

4. 获取集群健康

获取有关 Elasticsearch 集群的健康信息。

参数：

无需参数。

示例：

{}

5. 获取分片

检索所有或特定索引的分片信息。

参数：

index（可选，字符串）：要获取分片信息的特定索引。如果省略，则返回所有索引的分片。

示例：

{
  "index": "my-index"
}

6. 添加文档

将新文档插入特定 Elasticsearch 索引中。

参数：

index（必需，字符串）：文档将添加到的索引。
document（必需，对象）：要添加的文档内容。
id（可选，字符串）：文档 ID。如果省略，Elasticsearch 会自动生成一个。

示例：

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

7. 更新文档

修改特定 Elasticsearch 索引中的现有文档。

参数：

index（必需，字符串）：包含文档的索引。
id（必需，字符串）：要更新的文档 ID。
document（必需，对象）：包含要更新字段的部分文档。

示例：

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

8. 删除文档

从特定 Elasticsearch 索引中删除文档。

参数：

index（必需，字符串）：包含文档的索引。
id（必需，字符串）：要删除的文档 ID。

示例：

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

9. 通过查询更新

根据查询更新 Elasticsearch 索引中的文档。

参数：

index（必需，字符串）：要更新文档的索引。
query（必需，对象）：用于匹配要更新文档的 Elasticsearch 查询。
script（必需，对象）：用于更新匹配文档的脚本。
conflicts（可选，字符串）：如何处理版本冲突（“abort”或“proceed”，默认：“abort”）。
refresh（可选，布尔值）：操作后是否刷新索引（默认：false）。

示例：

{
  "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. 通过查询删除

根据查询删除 Elasticsearch 索引中的文档。

参数：

index（必需，字符串）：要删除文档的索引。
query（必需，对象）：用于匹配要删除文档的 Elasticsearch 查询。
conflicts（可选，字符串）：如何处理版本冲突（“abort”或“proceed”，默认：“abort”）。
refresh（可选，布尔值）：操作后是否刷新索引（默认：false）。

示例：

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

11. 批量操作

在单个 API 调用中执行多个文档操作以提高性能。

参数：

operations（必需，数组）：操作对象的数组，每个对象包含：
- action（必需，字符串）：操作类型（“index”，“create”，“update”或“delete”）。
- index（必需，字符串）：此操作的索引。
- id（可选，字符串）：文档 ID（更新/删除时必需，索引/创建时可选）。
- document（条件，对象）：文档内容（索引/创建/更新操作时必需）。

示例：

{
  "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. 创建索引

创建一个新的 Elasticsearch 索引，带有可选的设置和映射。

参数：

index（必需，字符串）：要创建的索引名称。
settings（可选，对象）：索引设置，如分片数、复制数等。
mappings（可选，对象）：字段映射，定义文档应如何被索引。

示例：

{
  "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. 删除索引

永久删除 Elasticsearch 索引。

参数：

index（必需，字符串）：要删除的索引名称。

示例：

{
  "index": "my-index"
}

14. 计数文档

计算索引中的文档数量，选项上可以通过查询进行过滤。

参数：

index（必需，字符串）：要计算文档的索引。
query（可选，对象）：用于过滤文档以进行计数的 Elasticsearch 查询。

示例：

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

15. 获取模板

从 Elasticsearch 检索索引模板。

参数：

name（可选，字符串）：要检索的特定模板名称。如果省略，则返回所有模板。

示例：

{
  "name": "logs-template"
}

16. 获取别名

从 Elasticsearch 获取索引别名。

参数：

name（可选，字符串）：要检索的特定别名名称。如果省略，则返回所有别名。

示例：

{
  "name": "logs-alias"
}

开发

在开发模式下运行

要在开发期间以监视模式运行服务器，请使用：

npm run dev

协议实现

该服务器实现了模型上下文协议，以促进 LLM 客户端与 Elasticsearch 之间的标准化通信。它提供了一整套工具，可以被 MCP 客户端调用以执行各种 Elasticsearch 操作。

添加新工具

要向服务器添加新工具：

使用 MCP 服务器的工具注册格式在 src/index.ts 中定义工具。
在 src/utils/elasticsearchService.ts 中实现必要的功能。
更新此 README 以记录新工具。

其他 MCP 客户端

Octodet Elasticsearch MCP 服务器可以与任何兼容 MCP 的客户端一起使用，包括：

通过 MCP 插件的 OpenAI 的 ChatGPT
Anthropic 的 Claude Desktop
VS Code 中的 Claude
使用 MCP SDK 的自定义应用程序

程序化使用

您还可以在 Node.js 应用程序中以编程方式使用服务器：

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

// 配置 Elasticsearch 连接
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// 创建并启动服务器
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // 连接到您的自定义传输
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Elasticsearch MCP 服务器已启动");
}

startServer().catch(console.error);

许可证

该项目根据 MIT 许可证授权 - 详细信息请参见 LICENSE 文件。

详情

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

Clone this repository
Install dependencies:

npm install

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:

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:

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

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.

Server配置

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