Octodet Elasticsearch MCPサーバー

Octodet Elasticsearch MCPサーバー

Octodet Elasticsearch MCPサーバーは、Elasticsearchクラスターとのシームレスなインタラクションのために設計された強力なモデルコンテキストプロトコル（MCP）サーバーです。LLM駆動のアプリケーションがElasticsearch内でデータの検索、更新、管理などのさまざまな操作を行うための標準化された方法を提供します。

機能

• 完全なElasticsearch操作: ドキュメントやインデックスに対して完全なCRUD操作を簡単に実行できます。
• バルク操作: 単一のAPI呼び出しで複数の操作を処理することでパフォーマンスを向上させます。
• クエリベースの更新/削除: 特定のクエリに基づいてドキュメントを変更または削除します。
• クラスター管理: シャードやテンプレートを含むElasticsearchクラスターの健康状態を監視します。
• 高度な検索: 組み込みのハイライトサポートを使用して、Elasticsearch DSLクエリの完全な機能を活用します。

インストール方法

NPMパッケージとして

Octodet Elasticsearch MCPサーバーをグローバルにインストールするには、次のコマンドを実行します：

npm install -g @octodet/elasticsearch-mcp

または、npxを使用して直接実行することもできます：

npx @octodet/elasticsearch-mcp

ソースから

1. リポジトリをクローンします。
2. 必要な依存関係をインストールします：

npm install

3. サーバーをビルドします：

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

設定

サーバーは次の環境変数を使用して構成できます：

変数	説明	デフォルト
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のパスプレフィックス

ツール

サーバーには、さまざまなElasticsearch操作のための16の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間の標準化された通信を促進するためにモデルコンテキストプロトコルを実装しています。さまざまなElasticsearch操作を実行するためにMCPクライアントによって呼び出される包括的なツールセットを提供します。

新しいツールの追加

サーバーに新しいツールを追加するには：

1. src/index.tsでMCPサーバーのツール登録形式を使用してツールを定義します。
2. src/utils/elasticsearchService.tsで必要な機能を実装します。
3. 新しいツールを文書化するためにこのREADMEを更新します。

その他のMCPクライアント

Octodet Elasticsearch MCPサーバーは、次のようなMCP互換クライアントで利用できます：

• OpenAIのChatGPTをMCPプラグイン経由で
• 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

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.