MCP Server: Elasticsearch semantic search tool

MCP Server：Elasticsearch セマンティック検索ツール

デモリポジトリ：https://j.blaszyk.me/tech-blog/mcp-server-elasticsearch-semantic-search/

目次

• 概要
• MCP サーバーの実行
• Claude Desktop との統合
• Search Labs のブログ記事のクロール
  • 1. クローラーの設定を確認する
  • 2. Elasticsearch を設定する
  • 3. セマンティック検索用にインデックスのマッピングを更新する
  • 4. クロールを開始する
  • 5. インデックスされたドキュメントを確認する

---

概要

このリポジトリでは、Elasticsearch にインデックスされた Search Labs のブログ記事をセマンティック検索するための、MCP サーバーの Python 実装を提供しています。

ブログ記事をクロールし、Elastic Open Crawler を使って search-labs-posts インデックスに保存していることを前提としています。

---

MCP サーバーの実行

.env ファイルに ES_URL と ES_AP_KEY を追加します（最小限の権限を持つ API キーの生成方法についてはこちらを参照してください）。

サーバーを MCP Inspector で起動します。

make dev

起動したら、MCP Inspector にアクセスします：http://localhost:5173

---

Claude Desktop との統合

Claude Desktop に MCP サーバーを追加するには、次のようにします。

make install-claude-config

これにより、ホームディレクトリの claude_desktop_config.json が更新されます。次回の再起動時に Claude アプリがサーバーを検出し、宣言されたツールを読み込みます。

---

Search Labs のブログ記事のクロール

1. クローラーの設定を確認する

Elastic Open Crawler が動作するか確認するには、次を実行します。

docker run --rm \
  --entrypoint /bin/bash \
  -v "$(pwd)/crawler-config:/app/config" \
  --network host \
  docker.elastic.co/integrations/crawler:latest \
  -c "bin/crawler crawl config/test-crawler.yml"

単一ページからクロールしたコンテンツが出力されます。

---

2. Elasticsearch を設定する

Elasticsearch の URL と API キーを設定します。

クローラーに必要な最小限の権限を持つ API キーを生成します。

POST /_security/api_key
{
  "name": "crawler-search-labs",
  "role_descriptors": {
    "crawler-search-labs-role": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["search-labs-posts"],
          "privileges": ["all"]
        }
      ]
    }
  },
  "metadata": {
    "application": "crawler"
  }
}

レスポンスの encoded 値をコピーし、API_KEY として設定します。

---

3. セマンティック検索用にインデックスのマッピングを更新する

search-labs-posts インデックスが存在することを確認します。存在しない場合は作成します。

PUT search-labs-posts

セマンティック検索を有効にするため、マッピングを更新します。

PUT search-labs-posts/_mappings
{
  "properties": {
    "body": {
      "type": "text",
      "copy_to": "semantic_body"
    },
    "semantic_body": {
      "type": "semantic_text",
      "inference_id": ".elser-2-elasticsearch"
    }
  }
}

body フィールドは、Elasticsearch の ELSER モデルを使用したセマンティックテキストとしてインデックスされます。

---

4. クロールを開始する

インデックスにデータを格納するため、クローラーを実行します。

docker run --rm \
  --entrypoint /bin/bash \
  -v "$(pwd)/crawler-config:/app/config" \
  --network host \
  docker.elastic.co/integrations/crawler:latest \
  -c "bin/crawler crawl config/elastic-search-labs-crawler.yml"

ヒント

新しい Elasticsearch クラスターを使用する場合は、インデックス作成を始める前に ELSER モデルが起動するまで待ちます。

---

5. インデックスされたドキュメントを確認する

ドキュメントがインデックスされたか確認します。

GET search-labs-posts/_count

インデックス内のドキュメント総数が返されます。Kibana でも確認できます。

---

完了です！ これで、Search Labs のブログ記事をセマンティック検索できます。