Elasticsearch MCP

🚀 Octodet Elasticsearch MCP Server

Elasticsearch操作を行うためのモデルコンテキストプロトコル（MCP）サーバーです。標準化されたモデルコンテキストプロトコルを通じて、Elasticsearchクラスターとの相互作用に必要な包括的なツールセットを提供します。このサーバーにより、LLMを搭載したアプリケーションがElasticsearchデータの検索、更新、管理を行うことが可能になります。

🚀 クイックスタート

このセクションでは、Octodet Elasticsearch MCP Serverの基本的な使い方を説明します。

✨ 主な機能

• 完全な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"
      }
    }
  }
}

サーバーの設定

サーバーは以下の環境変数を使用して設定されます。

ツールの使用例

このサーバーは、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

プロトコルの実装

このサーバーは、Model Context Protocolを実装しており、LLMクライアントと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ファイルを参照してください。