Octodet Elasticsearch Mcp

Octodet Elasticsearch MCP 服务

一个用于 Elasticsearch 操作的模型上下文协议（MCP）服务，通过标准化的模型上下文协议提供一套全面的工具，用于与 Elasticsearch 集群交互。此服务使由大模型驱动的应用能够搜索、更新和管理 Elasticsearch 数据。

功能

• 完整的 Elasticsearch 操作：对文档和索引执行完整的 CRUD 操作
• 批量操作：在单次 API 调用中处理多项操作
• 基于查询的更新／删除：根据查询修改或删除文档
• 集群管理：监控集群健康状况、分片和模板
• 高级搜索：全面支持 Elasticsearch DSL 查询并提供高亮功能

安装

作为 NPM 包安装

全局安装此包：

npm install -g @octodet/elasticsearch-mcp

也可以使用 npx 直接运行：

npx @octodet/elasticsearch-mcp

从源码安装

1. 克隆此仓库
2. 安装依赖：

npm install

3. 构建服务：

npm run build

与 MCP 客户端集成

VS Code 集成

将以下配置添加到 VS Code 的 settings.json 中，以便与 VS Code MCP 扩展集成：

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

配置

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

变量	说明	默认值
ES_URL	Elasticsearch 服务 URL	http://localhost:9200
ES_API_KEY	用于身份验证的 API 密钥
ES_USERNAME	用于身份验证的用户名
ES_PASSWORD	用于身份验证的密码
ES_CA_CERT	自定义 CA 证书的路径
ES_VERSION	Elasticsearch 版本（8 或 9）	8
ES_SSL_SKIP_VERIFY	跳过 SSL 验证	false
ES_PATH_PREFIX	Elasticsearch 的路径前缀

工具

此服务提供 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 将自动生成 ID

示例：

{
  "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（update/delete 必填，index/create 可选）
  • document（有条件必填，对象）：文档内容（index/create/update 操作必填）

示例：

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

协议实现

此服务实现了 Model Context Protocol，以便在大模型客户端与 Elasticsearch 之间进行标准化通信。它提供了一组工具，MCP 客户端可以调用这些工具来执行各种 Elasticsearch 操作。

添加新工具

要向服务添加新工具，请执行以下操作：

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

其他 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";

// 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);

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。