Jedrazb Elastic Semantic Search MCP Server

🚀 MCP Server: Elasticsearch Semantic Search Tool

This repository provides a Python implementation of an MCP server for semantic search on Elasticsearch using Search Labs blog posts. It assumes you've crawled the blog posts and stored them in the search-labs-posts index created with Elastic Open Crawler.

🚀 Quick Start

Run the MCP Server

Add ES_URL and ES_AP_KEY to the .env file (see here to generate an API key with minimal permissions). Start the server in the MCP Inspector:

make dev

After startup, access the MCP Inspector: http://localhost:5173

Integrate with Claude Desktop

To add the MCP server to Claude Desktop:

make install-claude-config

This updates the claude_desktop_config.json in your home directory. On the next restart, the Claude application will detect the server and load the declared tools.

Crawl Search Labs Blog Posts

1. Verify the Crawler Configuration

To check if Elastic Open Crawler is working, run:

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"

This should output the content crawled from a single page.

2. Configure Elasticsearch

Set the Elasticsearch URL and API key. Generate an API key with minimal crawler permissions:

POST /_security/api_key
{
  "name": "crawler-search-labs",
  "role_descriptors": {
    "crawler-search-labs-role": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["*"],
          "privileges": ["read", "write"]
        }
      ]
    }
  },
  "managed": true
}

Run the command to get the API key:

curl -X GET http://localhost:9200/_security/api_key \
  -H 'Content-Type: application/json' \
  -d '{"name":"crawler-search-labs"}'

Add the returned api_key and id to your .env file:

ES_URL=http://localhost:9200
ES_AP_KEY=your_api_key_here
ES_AP_ID=your_api_id_here

3. Update the Semantic Search Index Mapping

To enable dynamic field data and automatic mapping, update the Elasticsearch index mapping:

curl -X PUT http://localhost:9200/search-labs/_mapping \
  -H 'Content-Type: application/json' \
  -d '{"dynamic": true}'

4. Start Crawling

Start crawling Search Labs blog posts using the following command:

python3 crawler.py --config config/crawler_config.yml

An example of the crawler_config.yml content is as follows:

start_url: "https://search-labs.com/blog"
output_file: "blog_posts.json"
concurrency: 5
max_depth: 2

5. Verify the Indexed Documents

To verify if the blog posts are correctly indexed, run the following command:

curl -X GET http://localhost:9200/search-labs/_search \
  -H 'Content-Type: application/json' \
  -d '{"query":{"match_all":{}}}'

This will return all the indexed blog posts.

📚 Documentation

Create a .env File

ES_URL=http://localhost:9200