MCP Server: Elasticsearch semantic search tool

MCP 服务：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 服务

将 ES_URL 和 ES_AP_KEY 添加到 .env 文件中（如何生成具有最低权限的 API 密钥，请参阅此处）。

在 MCP Inspector 中启动服务：

make dev

服务运行后，访问 MCP Inspector：http://localhost:5173

---

与 Claude Desktop 集成

要将 MCP 服务添加到 Claude Desktop：

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 Key。

生成具有最低爬虫权限的 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 博文执行语义搜索。