Octodet Elasticsearch Mcp

Octodet Elasticsearch MCP サーバー

Elasticsearch クラスターを操作するための包括的なツールセットを提供する、Elasticsearch 操作用の Model Context Protocol（MCP）サーバーです。このサーバーを利用すると、LLM を活用したアプリケーションから Elasticsearch のデータを検索、更新、管理できます。

機能

• Elasticsearch の包括的な操作：ドキュメントとインデックスに対する完全な CRUD 操作
• 一括操作：1 回の 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 MCP 拡張機能と連携するには、以下の設定を VS Code の 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"
      }
    }
  }
}

設定

サーバーの設定には、以下の環境変数を使用します：

Variable	Description	Default
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（任意、string）：インデックスを絞り込むパターン（例：「logs-」、「my-index-」）

例：

{
  "indexPattern": "logs-*"
}

2. マッピングの取得

特定の Elasticsearch インデックスのフィールドマッピングを取得します。

パラメーター：

• index（必須、string）：マッピングを取得するインデックスの名前

例：

{
  "index": "my-index"
}

3. 検索

指定したクエリ DSL とハイライト機能を使用して、Elasticsearch 検索を実行します。

パラメーター：

• index（必須、string）：検索対象のインデックス（カンマ区切りの値をサポート）
• queryBody（必須、object）：Elasticsearch クエリ DSL の本文
• highlight（任意、boolean）：検索結果のハイライトを有効にします（デフォルト：true）

例：

{
  "index": "my-index",
  "queryBody": {
    "query": {
      "match": {
        "content": "search term"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. クラスターのヘルスを取得

Elasticsearch クラスターのヘルス情報を取得します。

パラメーター：

• 必須項目なし

例：

{}

5. シャードの取得

すべてのインデックス、または特定のインデックスのシャード情報を取得します。

パラメーター：

• index（任意、string）：シャード情報を取得する特定のインデックス。省略した場合は、すべてのインデックスのシャードを返します

例：

{
  "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. 一括操作

パフォーマンスを向上させるため、1 回の 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を実装し、LLM クライアントと Elasticsearch 間の標準化された通信を実現します。MCP クライアントから呼び出して、さまざまな Elasticsearch 操作を実行できるツールを提供します。

新しいツールの追加

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

1. MCP サーバーのツール登録形式を使用して、src/index.tsでツールを定義します
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ファイルをご覧ください。