Skip to main content

Elasticsearch MCP Server

Create a powerful Model Context Protocol (MCP) server for Elasticsearch in minutes with our AI Gateway. This guide walks you through setting up seamless search and analytics integration with enterprise-grade capabilities and instant API authentication.

About Elasticsearch API​

Elasticsearch is a distributed, RESTful search and analytics engine capable of addressing a growing number of use cases. The API provides comprehensive access to indexing, searching, and analyzing large volumes of data in near real-time.

Key Capabilities​

  • Full-Text Search: Advanced text analysis and search
  • Structured Queries: Complex filtering and aggregations
  • Analytics Engine: Real-time data analytics
  • Distributed Architecture: Horizontal scaling
  • Multi-tenancy: Index-level isolation
  • Near Real-time: Millisecond search latency
  • Schema-free: Dynamic mapping
  • RESTful API: JSON over HTTP

API Features​

  • Document APIs: CRUD operations on documents
  • Search APIs: Query DSL for complex searches
  • Aggregations: Analytics and metrics
  • Index APIs: Manage indices and mappings
  • Cluster APIs: Monitor and manage clusters
  • Ingest Pipelines: Data transformation
  • Security: Authentication and authorization
  • Machine Learning: Anomaly detection and forecasting

What You Can Do with Elasticsearch MCP Server​

The MCP server transforms Elasticsearch API into a natural language interface, enabling AI agents to:

Search Operations​

  • Full-Text Search

    • "Search for documents containing 'artificial intelligence'"
    • "Find products with 'wireless' in description"
    • "Search logs for error messages"
    • "Query articles about machine learning"

  • Filtered Searches

    • "Find orders from last week over $100"
    • "Search users in California"
    • "Get products in stock under $50"
    • "Find logs between specific dates"

  • Fuzzy Matching

    • "Search for 'intelligense' (with typos)"
    • "Find similar product names"
    • "Match approximate values"
    • "Phonetic searches"

Analytics and Aggregations​

  • Metrics

    • "Calculate average order value"
    • "Sum total revenue by month"
    • "Count unique visitors"
    • "Get min/max prices"

  • Bucket Aggregations

    • "Group sales by category"
    • "Histogram of prices"
    • "Date histogram of events"
    • "Terms aggregation by status"

  • Pipeline Aggregations

    • "Calculate moving averages"
    • "Compute cumulative sums"
    • "Derivative calculations"
    • "Bucket comparisons"

Document Management​

  • CRUD Operations

    • "Index new document"
    • "Update product details"
    • "Delete old records"
    • "Bulk import data"

  • Versioning

    • "Track document versions"
    • "Optimistic concurrency control"
    • "Conflict resolution"
    • "Version history"

Index Management​

  • Index Operations

    • "Create new index"
    • "Delete old indices"
    • "Reindex data"
    • "Clone index"

  • Mapping Management

    • "Define field types"
    • "Update mappings"
    • "Add new fields"
    • "Configure analyzers"

  • Index Templates

    • "Create index patterns"
    • "Auto-apply settings"
    • "Lifecycle policies"
    • "Rollover indices"

Cluster Management​

  • Health Monitoring

    • "Check cluster health"
    • "Monitor node status"
    • "View shard allocation"
    • "Track performance metrics"

  • Configuration

    • "Update cluster settings"
    • "Manage node roles"
    • "Configure allocation"
    • "Set routing rules"

Advanced Features​

  • Geospatial Queries

    • "Find stores within 10km"
    • "Search by polygon area"
    • "Calculate distances"
    • "Geo aggregations"

  • Machine Learning

    • "Detect anomalies in metrics"
    • "Forecast future trends"
    • "Classify documents"
    • "Find outliers"

  • Percolator Queries

    • "Match documents to queries"
    • "Real-time alerting"
    • "Saved search monitoring"
    • "Reverse search"

Prerequisites​

  • Access to Cequence AI Gateway
  • Elasticsearch cluster (self-hosted or cloud)
  • Cluster endpoint URL
  • Authentication credentials (if secured)

Step 1: Configure Elasticsearch Access​

1.1 Cluster Connection​

  1. Note your Elasticsearch endpoint:
    • Self-hosted: http://localhost:9200
    • Elastic Cloud: https://cluster-id.region.cloud-provider.elastic-cloud.com
  2. Ensure cluster is accessible
  3. Test connection with curl

1.2 Authentication Setup​

For secured clusters:

  1. Basic Auth: Username and password
  2. API Keys: Generate from Kibana
  3. Cloud ID: For Elastic Cloud deployments
  4. Certificates: For TLS/SSL connections

1.3 Security Configuration​

# Generate API key
POST /_security/api_key
{
  "name": "ai-gateway-key",
  "role_descriptors": {
    "ai_gateway_role": {
      "cluster": ["monitor", "manage"],
      "index": [
        {
          "names": ["*"],
          "privileges": ["all"]
        }
      ]
    }
  }
}

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find Elasticsearch API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: Your Elasticsearch endpoint
  2. API Version: v7.x or v8.x
  3. Index Patterns: Specify accessible indices
  4. Click Next

Step 6: MCP Server Configuration​

  1. Name: "Elasticsearch Search"
  2. Description: "Search and analytics engine"
  3. Request Timeout: 30 seconds (for complex queries)
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: Choose based on setup:
    • Basic Authentication
    • API Key
    • Bearer Token
    • No Auth (for local development)
  2. Enter credentials
  3. Test connection

Available Elasticsearch API Operations​

Search APIs​

  • Search

    • Query DSL
    • Request body search
    • URI search
    • Multi-index search

  • Multi Search

    • Batch queries
    • Different indices
    • Optimized performance
    • Reduced overhead

  • Scroll & Search After

    • Large result sets
    • Pagination
    • Point in time
    • Consistent results

Document APIs​

  • Index/Create

    • Add documents
    • Auto-generate IDs
    • Versioning
    • Refresh control

  • Get/Multi-Get

    • Retrieve by ID
    • Source filtering
    • Stored fields
    • Batch retrieval

  • Update/Delete

    • Partial updates
    • Scripts
    • Delete by query
    • Bulk operations

Index APIs​

  • Create Index

    • Settings
    • Mappings
    • Aliases
    • Lifecycle

  • Index Management

    • Open/Close
    • Freeze/Unfreeze
    • Shrink/Split
    • Rollover

Aggregation Types​

  • Metrics: sum, avg, min, max, stats
  • Bucket: terms, histogram, date_histogram, range
  • Pipeline: moving_avg, cumulative_sum, bucket_script
  • Matrix: stats, covariance, correlation

Step 8-10: Complete Setup​

Configure security settings, choose deployment options, and deploy your server.

Using Your Elasticsearch MCP Server​

With Claude Desktop​

{
  "servers": {
    "elasticsearch": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "apikey",
        "apikey": "your-api-key"
      },
      "config": {
        "cluster_url": "https://your-cluster.elastic.co",
        "indices": ["products", "orders", "logs"]
      }
    }
  }
}

Natural Language Commands​

  • "Search for products containing 'laptop' under $1000"
  • "Show me error logs from the last hour"
  • "Calculate average response time by endpoint"
  • "Find top 10 customers by order count"
  • "Analyze sentiment in customer reviews"

API Integration Example​

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'apikey',
    apikey: 'your-api-key'
  }
});

// Full-text search
const searchResults = await mcpClient.elasticsearch.search({
  index: 'products',
  body: {
    query: {
      match: {
        description: 'wireless headphones'
      }
    },
    size: 20,
    from: 0
  }
});

console.log(`Found ${searchResults.hits.total.value} products`);

// Complex filtered search
const filteredSearch = await mcpClient.elasticsearch.search({
  index: 'orders',
  body: {
    query: {
      bool: {
        must: [
          { range: { order_date: { gte: '2025-01-01' } } },
          { range: { total_amount: { gte: 100 } } }
        ],
        filter: [
          { term: { status: 'completed' } },
          { terms: { payment_method: ['credit_card', 'paypal'] } }
        ]
      }
    },
    aggs: {
      revenue_by_day: {
        date_histogram: {
          field: 'order_date',
          calendar_interval: 'day'
        },
        aggs: {
          daily_revenue: {
            sum: { field: 'total_amount' }
          }
        }
      }
    }
  }
});

// Index a document
const indexResult = await mcpClient.elasticsearch.index({
  index: 'products',
  id: 'prod-12345',
  body: {
    name: 'Wireless Noise-Canceling Headphones',
    description: 'Premium headphones with active noise cancellation',
    price: 299.99,
    category: 'Electronics',
    brand: 'AudioTech',
    features: ['Bluetooth 5.0', '30-hour battery', 'ANC'],
    in_stock: true,
    created_at: new Date().toISOString()
  }
});

// Bulk operations
const bulkOps = await mcpClient.elasticsearch.bulk({
  body: [
    { index: { _index: 'products', _id: '1' } },
    { name: 'Product 1', price: 99.99 },
    { update: { _index: 'products', _id: '2' } },
    { doc: { price: 149.99, on_sale: true } },
    { delete: { _index: 'products', _id: '3' } }
  ]
});

// Aggregation query
const analytics = await mcpClient.elasticsearch.search({
  index: 'orders',
  body: {
    size: 0,
    aggs: {
      sales_over_time: {
        date_histogram: {
          field: 'order_date',
          calendar_interval: 'month'
        },
        aggs: {
          revenue: { sum: { field: 'total_amount' } },
          order_count: { value_count: { field: 'order_id' } },
          avg_order_value: { avg: { field: 'total_amount' } }
        }
      },
      top_categories: {
        terms: {
          field: 'product_category.keyword',
          size: 10
        },
        aggs: {
          category_revenue: { sum: { field: 'total_amount' } }
        }
      }
    }
  }
});

// Geospatial search
const nearbyStores = await mcpClient.elasticsearch.search({
  index: 'stores',
  body: {
    query: {
      bool: {
        must: { match_all: {} },
        filter: {
          geo_distance: {
            distance: '10km',
            location: {
              lat: 40.73,
              lon: -73.93
            }
          }
        }
      }
    },
    sort: [
      {
        _geo_distance: {
          location: { lat: 40.73, lon: -73.93 },
          order: 'asc',
          unit: 'km'
        }
      }
    ]
  }
});

// Machine Learning - Anomaly Detection
const anomalyJob = await mcpClient.elasticsearch.ml.putJob({
  job_id: 'response_time_anomaly',
  analysis_config: {
    bucket_span: '15m',
    detectors: [{
      detector_description: 'High response time',
      function: 'high_mean',
      field_name: 'response_time_ms'
    }]
  },
  data_description: {
    time_field: '@timestamp'
  }
});

// Create index with custom mapping
const createIndex = await mcpClient.elasticsearch.indices.create({
  index: 'customer_feedback',
  body: {
    settings: {
      number_of_shards: 3,
      number_of_replicas: 1,
      analysis: {
        analyzer: {
          custom_analyzer: {
            type: 'custom',
            tokenizer: 'standard',
            filter: ['lowercase', 'stop', 'snowball']
          }
        }
      }
    },
    mappings: {
      properties: {
        feedback_text: {
          type: 'text',
          analyzer: 'custom_analyzer'
        },
        sentiment_score: { type: 'float' },
        customer_id: { type: 'keyword' },
        created_at: { type: 'date' },
        product_id: { type: 'keyword' },
        rating: { type: 'integer' }
      }
    }
  }
});

// Monitor cluster health
const clusterHealth = await mcpClient.elasticsearch.cluster.health();
console.log(`Cluster status: ${clusterHealth.status}`);
console.log(`Number of nodes: ${clusterHealth.number_of_nodes}`);
console.log(`Active shards: ${clusterHealth.active_shards}`);

// SQL query interface
const sqlResults = await mcpClient.elasticsearch.sql.query({
  body: {
    query: `
      SELECT category, COUNT(*) as product_count, AVG(price) as avg_price
      FROM "products"
      WHERE in_stock = true
      GROUP BY category
      ORDER BY product_count DESC
      LIMIT 10
    `
  }
});

Common Use Cases​

Log Analytics​

  • Centralized logging
  • Error tracking
  • Performance monitoring
  • Security analysis
  • Product search
  • Faceted navigation
  • Recommendation engine
  • Inventory tracking

Full-Text Search​

  • Document search
  • Knowledge base
  • Content discovery
  • Semantic search

Real-time Analytics​

  • Metrics aggregation
  • Dashboard data
  • Trend analysis
  • Anomaly detection

Best Practices​

  1. Index Design:

    • Plan mappings carefully
    • Use appropriate field types
    • Consider search requirements
    • Optimize for your queries

  2. Query Optimization:

    • Use filters for exact matches
    • Leverage caching
    • Limit result size
    • Use source filtering

  3. Performance Tuning:

    • Monitor cluster health
    • Configure appropriate shards
    • Use bulk operations
    • Implement pagination

Troubleshooting​

Common Issues​

  1. Connection Errors

    • Verify cluster URL
    • Check network connectivity
    • Validate certificates
    • Test authentication

  2. Query Performance

    • Review query complexity
    • Check index size
    • Monitor resource usage
    • Optimize mappings

  3. Data Issues

    • Verify mapping conflicts
    • Check data types
    • Handle null values
    • Review analyzers

Getting Help​