Skip to main content
Glama
Elasticsearch MCP (VSee Fork)

Elasticsearch MCP (VSee Fork)

by mlei06

Elasticsearch MCP (VSee Fork)

Modified MCP server with hardcoded schemas matching VSee's Elasticsearch indexes. Specialized analytics tools optimized for stats- indices.*

npm version TypeScript Elasticsearch License: MIT

elasticsearch-mcp-vsee is a modified Model Context Protocol (MCP) server that provides specialized analytics tools for Elasticsearch clusters, optimized for VSee's stats-* indices. This fork features hardcoded schemas and field names that match VSee's specific Elasticsearch index structure, enabling specialized tools for account/group analytics, visit trends, platform breakdowns, and rating distributions. Built with TypeScript and optimized for Elastic Cloud environments, it offers comprehensive analytics capabilities with enterprise-grade security features.

πŸš€ Features

  • πŸ” Secure by Design: Input validation, script sanitization, injection prevention

  • ☁️ Elastic Cloud Ready: Native support for cloud ID and API key authentication

  • ⚑ High Performance: Connection pooling, optimized query execution, efficient aggregations

  • πŸ› οΈ Comprehensive Tools: 11 specialized tools for analytics, summaries, and data exploration

  • πŸ“Š Advanced Querying: Full Elasticsearch DSL support with aggregations and highlighting

  • πŸ” Smart Validation: Zod-based schemas with security-first validation

  • πŸ“ Full TypeScript: Complete type safety with strict null checks

🎯 Purpose

This MCP server is designed for VSee's Open WebUI deployment to provide specialized analytics tools for querying VSee's Elasticsearch stats-* indices. It integrates with VSee's Open WebUI infrastructure via MCPO (MCP OpenAPI bridge) to expose Elasticsearch analytics capabilities to LLMs.

πŸ“¦ Usage with VSee's Open WebUI Deployment

This MCP server is automatically loaded by VSee's Open WebUI deployment through the MCP configuration. It connects to VSee's Elasticsearch deployment to provide analytics on visit statistics, account/group metrics, platform breakdowns, and more.

Configuration

The MCP server is configured in vsee/mcp/config.json:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "elasticsearch-mcp-vsee"],
      "env": {
        "ELASTIC_NODE": "https://omtm.es.us-east-1.aws.found.io",
        "ELASTIC_USERNAME": "your-username",
        "ELASTIC_PASSWORD": "your-password",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

The Open WebUI deployment automatically loads this configuration and starts the MCP server via MCPO, making all 11 tools available to the LLM for querying Elasticsearch data.

πŸ”„ Updating and Publishing

Making Changes

  1. Develop locally: Make changes to the code in elasticsearch-mcp/

  2. Test your changes: Use npm run test:tools to test against your Elasticsearch instance

  3. Build: Run npm run build to compile TypeScript

  4. Publish: Publish to npm with npm publish --access public

    • Make sure to increment the version in package.json first

Updating VSee's Deployment

After publishing a new version to npm:

  1. Update vsee/mcp/config.json: Change the package version in the args array:

    {
      "mcpServers": {
        "elasticsearch": {
          "command": "npx",
          "args": ["-y", "elasticsearch-mcp-vsee@0.5.0"],  // Update version here
          "env": {
            ...
          }
        }
      }
    }
  2. Restart the MCPO service: The MCPO container will automatically download and use the new version on restart:

    docker compose -f docker-compose.vsee.yaml restart mcpo
  3. Verify: Check that the new version is loaded by examining the MCPO logs or testing the tools in Open WebUI.

Note: You can also use @latest to always pull the latest version, but specifying a version number is recommended for production stability.

πŸ› οΈ Available Tools

Tool

Description

Use Cases

get_index_fields

Discover index fields and types

Schema exploration, field discovery

top_change

Find top accounts or groups with highest visit increase/decrease

Trend analysis, account/group monitoring

get_subscription_breakdown

Compare subscription tiers with metrics per tier

Subscription-tier analysis and comparisons

get_platform_breakdown

Platform or platform version breakdown (provider/patient, platform/version)

Platform adoption, device preferences, version analysis

get_rating_distribution

Rating histograms with statistics

Satisfaction analysis

get_visit_trends

Time series visit trends (daily/weekly/monthly)

Trend visualization

get_usage_profile

Comprehensive metrics summary with flexible filtering and grouping

Multi-dimensional analysis and comparisons

get_usage_leaderboard

Ranked leaderboard of accounts/groups/platforms

High-usage entities, outliers

πŸ“‹ Tool Examples

Get Account Summary

{
  "tool": "get_account_summary",
  "arguments": {
    "account": "example-customer",
    "startDate": "now-1y",
    "endDate": "now"
  }
}

Get Top Accounts by Growth

{
  "tool": "top_change",
  "arguments": {
    "groupBy": "account",
    "direction": "increase",
    "topN": 10,
    "currentPeriodDays": 30,
    "previousPeriodDays": 30
  }
}

Get Platform Breakdown

{
  "tool": "get_platform_breakdown",
  "arguments": {
    "role": "provider",
    "breakdownType": "version",
    "topN": 10,
    "startDate": "now-30d",
    "endDate": "now"
  }
}
{
  "tool": "get_visit_trends",
  "arguments": {
    "interval": "daily",
    "startDate": "now-30d",
    "endDate": "now",
    "groupBy": "subscription"
  }
}

βš™οΈ Configuration

Environment Variables

The MCP server reads configuration from environment variables. These are set in vsee/mcp/config.json under the env section:

Variable

Description

Required

Example

ELASTIC_NODE

Elasticsearch URL

Yes

https://omtm.es.us-east-1.aws.found.io

ELASTIC_USERNAME

Basic auth username

Yes

your-username

ELASTIC_PASSWORD

Basic auth password

Yes

your-password

NODE_TLS_REJECT_UNAUTHORIZED

Disable TLS verification (for self-signed certs)

No

"0"

Alternative: Elastic Cloud Authentication

If using Elastic Cloud with cloud ID and API key:

Variable

Description

Required

ELASTIC_CLOUD_ID

Elastic Cloud deployment ID

Yes*

ELASTIC_API_KEY

Elasticsearch API key

Yes*

*Either ELASTIC_CLOUD_ID + ELASTIC_API_KEY OR ELASTIC_NODE + ELASTIC_USERNAME + ELASTIC_PASSWORD is required

πŸ”’ Security Features

Input Validation

  • Zod Schemas: Strict type validation for all inputs

  • Field Name Validation: Prevents reserved field usage

  • Size Limits: Document size, array length, string length limits

  • Depth Validation: Prevents deeply nested objects/queries

Script Security

  • Script Sanitization: Blocks dangerous script patterns

  • Parameter Validation: Validates script parameters

  • Execution Limits: Prevents resource exhaustion

Query Security

  • Injection Prevention: Sanitizes and validates all queries

  • Script Query Blocking: Prevents script-based queries in sensitive operations

  • Rate Limiting: Protects against abuse

Data Protection

  • Credential Masking: Never logs sensitive information

  • Secure Connections: TLS/SSL support

  • Access Control: Validates permissions before operations

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   MCP Client    │◄──►│Elasticsearch MCP│◄──►│  Elasticsearch  β”‚
β”‚  (Claude, etc.) β”‚    β”‚     Server      β”‚    β”‚    Cluster      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                              β”‚
                       β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                       β”‚   Tools     β”‚
                       β”‚             β”‚
                       β”‚ β€’ search    β”‚
                       β”‚ β€’ fields    β”‚
                       β”‚ β€’ summaries β”‚
                       β”‚ β€’ trends    β”‚
                       β”‚ β€’ analytics β”‚
                       β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ“Š Performance

Benchmarks

  • Search: <500ms average response time

  • Aggregations: Optimized for large-scale analytics

  • Memory Usage: <100MB for typical operations

  • Concurrent Requests: Up to 10 simultaneous operations

Optimization Features

  • Connection Pooling: Reuses Elasticsearch connections

  • Optimized Queries: Efficient aggregation pipelines

  • Smart Caching: Reduced redundant queries

  • Health Monitoring: Automatic reconnection on failures

πŸ”§ Development

Setup Development Environment

# Install dependencies
npm install

# Set up environment variables
export ELASTIC_NODE="https://your-elasticsearch-url"
export ELASTIC_USERNAME="your-username"
export ELASTIC_PASSWORD="your-password"
export NODE_TLS_REJECT_UNAUTHORIZED="0"  # If needed for self-signed certs

# Run in development mode
npm run dev

# Test tools against live Elasticsearch
npm run test:tools

# Build for production
npm run build

# Publish new version (after incrementing version in package.json)
npm publish --access public

Project Structure

elasticsearch-mcp/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ tools/           # MCP tool implementations
β”‚   β”œβ”€β”€ elasticsearch/   # ES client and connection management
β”‚   β”œβ”€β”€ validation/      # Input validation schemas
β”‚   β”œβ”€β”€ errors/          # Error handling utilities
β”‚   β”œβ”€β”€ config.ts        # Configuration management
β”‚   β”œβ”€β”€ logger.ts        # Structured logging
β”‚   └── server.ts        # Main MCP server
β”œβ”€β”€ tests/               # Test suite
└── build/               # Compiled output

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

🏷️ Version History

  • v0.5.17 - Refined analytics tools: simplified metrics, removed unused ratings/duration fields from specific tools

  • v0.5.0 - Added find_entities_by_metric tool with multi-metric filtering support, updated default limits

  • v0.4.0 - Tool consolidation: merged 14 tools into 11 specialized analytics tools

  • v0.3.0 - Specialized analytics tools for stats-* indices

  • Full changelog: CHANGELOG.md


Built for VSee by VSee

Available Tools

8 tools
find_entities_by_metricA

Find groups or accounts filtered by metrics. Supports single metric (legacy) or multiple metrics (recommended). Available metrics: account_count (groups only), visit_count, provider_rating, patient_rating, avg_call_duration, unique_providers, unique_patients, provider_rating_count, patient_rating_count. Can filter accounts by group. Returns entities matching ALL criteria with their metric values.

Inputs: entityType (required), metric, min, max, +6 more.

get_index_fieldsA

Get all fields from an Elasticsearch index with optional filtering by field name and type. Use this tool when you need to discover available fields, their types, and correct field names before constructing queries. This is especially useful when unsure about field names or when looking for fields with specific types (e.g., keyword fields for exact matches or text fields for full-text search). ⚠️ IMPORTANT: Do NOT specify the index parameter unless the user explicitly requests fields from a different index. The tool defaults to "stats-*" which covers all standard indices. Only include the index parameter if the user specifically mentions a different index name.

Inputs: index, fieldFilter, typeFilter, includeNested.

get_platform_breakdownA

Get breakdown of top N platforms or platform versions by usage over a time period, can optionally be filtered by account or group. Supports both provider and patient roles. Returns top N items (default 10) plus "Other" category if needed, with metrics per item including visit counts, unique accounts/providers/patients, ratings, and call duration.

Inputs: role (required), breakdownType (required), topN, startDate, +3 more.

get_rating_distributionA

Get rating distribution (histogram) for provider and/or patient ratings over a time period. Returns rating buckets with counts and percentages, plus statistics (average, min, max, total count). Supports grouping by subscription, account, or group for comparative analysis.

Inputs: ratingType (required), bucketSize, startDate, endDate, +4 more.

get_subscription_breakdownA

Compare subscription tiers (Enterprise, Premium, FVC, BVC, Plus) across a time period. Always returns metrics grouped by subscription tier with per-tier breakdown (visits, accounts, providers, patients, ratings, call duration) plus totals.

Inputs: startDate, endDate.

get_usage_summaryB

Get usage summary for a time period, can optionally be filtered by account, group, or subscription. Returns visits, unique counts, ratings, call duration plus distribution breakdowns (subscription tiers, provider platforms, patient platforms).

Inputs: startDate, endDate, account, group, +2 more.

top_changeA

Find top N accounts or groups with highest visit/usage increase or decrease between two consecutive time periods. Returns items ranked by change with current period count, previous period count, absolute change, and percentage change. The previous period is automatically calculated to match the duration of the current period, ending where the current period starts. Supports filtering by subscription tier.

Inputs: groupBy (required), direction (required), topN, startDate, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. For example, find_entities_by_metric filters entities by metrics, get_usage_summary provides aggregated usage data, and get_visit_trends focuses on time-series trends. The descriptions reinforce non-overlapping functionalities, making tool selection straightforward.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., get_usage_summary, find_entities_by_metric, top_change). The naming is uniform across all eight tools, using snake_case and descriptive terms that clearly indicate their functions without any deviations or mixed conventions.

    Tool Count5/5

    With 8 tools, the server is well-scoped for analytics and data retrieval in an Elasticsearch context. Each tool serves a specific analytical purpose (e.g., breakdowns, trends, distributions), and none appear redundant or trivial, making the count appropriate for the domain.

    Completeness4/5

    The toolset covers core analytics operations like summaries, trends, breakdowns, and distributions, with good coverage for metrics such as visits, ratings, and subscriptions. A minor gap exists in CRUD operations (e.g., creating or updating data), but this is reasonable given the server's focus on querying and analysis rather than data manipulation.

    Related MCP Connectors