Elasticsearch MCP (VSee Fork)
This Elasticsearch MCP server provides specialized analytics tools for VSee's stats-* indices, enabling comprehensive business intelligence through secure, high-performance queries.
Core Capabilities:
Schema Discovery (
get_index_fields) - Explore available fields and types to understand data structure before queryingTrend Analysis (
top_change) - Identify accounts/groups with highest visit increases or decreases between periods with percentage change calculationsSubscription Analytics (
get_subscription_breakdown) - Compare metrics across tiers (Enterprise, Premium, FVC, BVC, Plus) including visits, accounts, ratings, and call durationPlatform Insights (
get_platform_breakdown) - Analyze Web/iOS/Android adoption and version distributions for providers and patientsRating Analysis (
get_rating_distribution) - Generate rating histograms with statistics, supporting grouping by subscription, account, or groupTime Series Trends (
get_visit_trends) - Visualize visit patterns over daily, weekly, or monthly intervals with optional multi-dimensional groupingUsage Summaries (
get_usage_summary) - Get comprehensive overviews including visits, unique users, ratings, call duration, and distribution breakdownsEntity Filtering (
find_entities_by_metric) - Find accounts or groups based on metric thresholds with support for multi-metric filtering
Technical Features:
Security - Input validation (Zod-based), script sanitization, injection prevention, and credential masking
Performance - Connection pooling, optimized aggregations, and smart caching for sub-500ms response times
Flexibility - Filter by subscription tier, account, group, and date ranges across all tools
Enterprise-Ready - Built with TypeScript for type safety, supports Elastic Cloud (Cloud ID/API key or username/password authentication), and designed for VSee's Open WebUI deployment with hardcoded schemas
Native support for Elastic Cloud deployments with cloud ID and API key authentication, enabling analytics and querying capabilities on cloud-hosted Elasticsearch instances.
Provides specialized analytics tools for querying Elasticsearch clusters, including account/group analytics, visit trends, platform breakdowns, rating distributions, and comprehensive metrics summaries with support for aggregations and time-series analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Elasticsearch MCP (VSee Fork) show me the top 10 accounts with the highest visit increase this month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Elasticsearch MCP (VSee Fork)
Modified MCP server with hardcoded schemas matching VSee's Elasticsearch indexes. Specialized analytics tools optimized for stats- indices.*
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
Develop locally: Make changes to the code in
elasticsearch-mcp/Test your changes: Use
npm run test:toolsto test against your Elasticsearch instanceBuild: Run
npm run buildto compile TypeScriptPublish: Publish to npm with
npm publish --access publicMake sure to increment the version in
package.jsonfirst
Updating VSee's Deployment
After publishing a new version to npm:
Update
vsee/mcp/config.json: Change the package version in theargsarray:{ "mcpServers": { "elasticsearch": { "command": "npx", "args": ["-y", "elasticsearch-mcp-vsee@0.5.0"], // Update version here "env": { ... } } } }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 mcpoVerify: 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 |
| Discover index fields and types | Schema exploration, field discovery |
| Find top accounts or groups with highest visit increase/decrease | Trend analysis, account/group monitoring |
| Compare subscription tiers with metrics per tier | Subscription-tier analysis and comparisons |
| Platform or platform version breakdown (provider/patient, platform/version) | Platform adoption, device preferences, version analysis |
| Rating histograms with statistics | Satisfaction analysis |
| Time series visit trends (daily/weekly/monthly) | Trend visualization |
| Comprehensive metrics summary with flexible filtering and grouping | Multi-dimensional analysis and comparisons |
| 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 |
| Elasticsearch URL | Yes |
|
| Basic auth username | Yes |
|
| Basic auth password | Yes |
|
| Disable TLS verification (for self-signed certs) | No |
|
Alternative: Elastic Cloud Authentication
If using Elastic Cloud with cloud ID and API key:
Variable | Description | Required |
| Elastic Cloud deployment ID | Yes* |
| 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 publicProject 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_metrictool with multi-metric filtering support, updated default limitsv0.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
Built for VSee by VSee
Available Tools
8 toolsfind_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.
get_visit_trendsA
Get visit/usage count trends over time (daily, weekly, or monthly intervals) with optional grouping by subscription, account, or group. Returns time series data points with visit counts and unique counts (accounts, providers, patients) per period.
Inputs: interval (required), startDate, endDate, groupBy, +3 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
Scored across 8 tools
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.
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.
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.
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
Read-only Yandex Metrika MCP. Query visits, sources, geo, devices and more in plain language.
Read-only web and revenue analytics: visitors, sources, goals, funnels and sales tied to visits.
Query PanDev Metrics analytics and reporting data
Per-customer API usage analytics: sign up, get ingest snippets, read usage by customer and endpoint.