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ファイルを参照してください。