Elasticsearch MCP (VSee Fork)

Modified MCP server with hardcoded schemas for VSee's Elasticsearch indexes.

elasticsearch-mcp-vsee is a 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.

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.

🔄 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'
5. Update VSee's Deployment: Update the MCP configuration in vsee/mcp/config.json to use the new version of the MCP server

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"
  }
}

Get Visit Trends

{
  "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

🔗 Links

• npm Package
• Elasticsearch Documentation
• Model Context Protocol

Built for VSee by VSee