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 桌面集成

對於 Claude 桌面，請按如下方式配置您的設置：

{
  "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 個 MCP 工具，用於各種 Elasticsearch 操作，每個工具都有所需和可選參數的文檔。

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 操作。

添加新工具

要將新工具添加到伺服器：

在 src/index.ts 中使用 MCP 伺服器的工具註冊格式定義該工具。
在 src/utils/elasticsearchService.ts 中實現必要的功能。
更新此 README 以記錄新工具。

其他 MCP 客戶端

Octodet Elasticsearch MCP 伺服器可以與任何兼容 MCP 的客戶端一起使用，包括：

OpenAI 的 ChatGPT 通過 MCP 插件
Anthropic 的 Claude 桌面
Claude 在 VS Code 中
使用 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.

伺服器配置

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

專案資訊

作者

Octodet