elasticsearch-mcp-server

FynnianB/elasticsearch-mcp-server

3.2

If you are the rightful owner of elasticsearch-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Elasticsearch MCP Server is designed to integrate Elasticsearch with multi-team and multi-environment support, enabling AI assistants to efficiently search exceptions, analyze patterns, and query logs securely.

Tools
5
Resources
0
Prompts
0

Elasticsearch MCP Server

A Model Context Protocol (MCP) server for Elasticsearch integration with multi-team and multi-environment support. This server allows AI assistants to search exceptions, analyze patterns, and query logs across different teams and environments in a secure and organized way.

Features

  • Multi-Team Support: Configure multiple teams with their own Elasticsearch clusters
  • Multi-Environment Support: Support for development, staging, production environments per team
  • Exception Search: Flexible exception search with filtering and frequency sorting
  • Exception Analysis: Deep analysis of specific exceptions with cause and solution suggestions
  • Trend Analysis: Analyze exception patterns, frequency trends, and service health
  • Log Search: Search application logs with various filters
  • Connection Testing: Test Elasticsearch connections for teams and environments
  • Flexible Authentication: Support for API keys and username/password authentication
  • HTTP and STDIO Transport: Support for both HTTP+SSE and STDIO transport protocols

Installation

npm install

Configuration

Environment Variables

  • LOG_LEVEL: Logging level (default: info) - handled directly by the logger
  • HTTP_PATH_PREFIX: HTTP path prefix (default: /)
  • TEAMS_CONFIG_PATH: Path to teams configuration file (optional)
  • PORT: HTTP server port (default: 3000)

Teams Configuration

Create a teams-config.json file based on teams-config.example.json:

{
  "server": {
    "name": "elasticsearch-mcp",
    "version": "1.0.0"
  },
  "teams": {
    "team-alpha": {
      "teamId": "team-alpha",
      "teamName": "Team Alpha",
      "defaultEnvironment": "production",
      "environments": {
        "staging": {
          "node": "https://alpha-staging-es.company.com",
          "apiKey": "your-api-key"
        },
        "production": {
          "node": "https://alpha-prod-es.company.com",
          "apiKey": "your-api-key"
        }
      },
      "indexPatterns": {
        "exceptions": ["alpha-logs-*", "alpha-exceptions-*"],
        "applications": ["alpha-apm-*", "alpha-metrics-*"],
        "logs": ["alpha-app-logs-*"]
      },
      "maxSearchResults": 50,
      "allowedOperations": ["search_exceptions", "analyze_exception", "analyze_trends", "search_logs", "test_connection"]
    }
  }
}
Configuration Options
  • teamId: Unique identifier for the team
  • teamName: Human-readable team name
  • defaultEnvironment: Default environment to use when none specified
  • environments: Elasticsearch connection configurations per environment
    • node: Elasticsearch cluster URL
    • apiKey: API key for authentication (optional)
    • username/password: Basic authentication (optional)
    • maxRetries: Maximum retry attempts (default: 3)
    • requestTimeout: Request timeout in milliseconds (default: 30000)
  • indexPatterns: Index patterns for different data types
    • exceptions: Patterns for exception/error logs
    • applications: Patterns for application metrics/APM data
    • logs: Patterns for general application logs
  • maxSearchResults: Maximum number of results to return (default: 50)
  • allowedOperations: List of allowed operations for this team (optional)

Usage

STDIO Mode (for MCP clients)

npm run dev
# or
npm start

HTTP Mode (for web interfaces)

npm run start-http
# or
npm run dev -- --http

The HTTP server will be available at:

  • SSE endpoint: GET http://localhost:3000/sse
  • Messages endpoint: POST http://localhost:3000/messages
  • Health check: GET http://localhost:3000/health

Available Tools

1. search_exceptions 🔍

Flexible exception search with advanced filtering and sorting capabilities.

Parameters:

  • environment (optional): The environment to search in
  • message (optional): Filter by exception message content
  • query (optional): Search term for exception message or stack trace
  • service (optional): Filter by service name
  • severity (optional): Filter by log severity level
  • timeRange (optional): Custom time range
    • start: Start time in ISO format
    • end: End time in ISO format
  • timeframe (optional): Predefined time frame (1h, 6h, 12h, 24h, 7d)
  • limit (optional): Number of results to return (default: 20, max: 100)
  • sortByFrequency (optional): Sort by frequency (most frequent first)

Use Cases:

  • "Welche Exceptions passen zu diesem Commit/Pull Request?"
  • "Zeige mir alle Database-Exceptions der letzten 6 Stunden"
  • "Finde die häufigsten Exceptions im User-Service"

2. analyze_exception 🔬

Deep analysis of a specific exception with causes and solution suggestions.

Parameters:

  • environment (optional): The environment to analyze
  • exceptionMessage (required): The specific exception message to analyze
  • timeframe (optional): Time frame for analysis (default: 24h)

Use Cases:

  • "Analysiere diese Exception: 'NullPointerException in UserService'"
  • "Was ist die Ursache für 'Connection timeout' Fehler?"

3. analyze_trends 📈

Analyze exception patterns, frequency trends, and service health over time.

Parameters:

  • environment (optional): The environment to analyze
  • timeRange (optional): Custom time range for analysis
  • timeframe (optional): Predefined time frame (default: 24h)
  • analysisType (optional): Type of analysis (exceptions, services, both)
  • services (optional): List of specific services to analyze

Use Cases:

  • "Welche Exceptions sind in den letzten 24h häufiger aufgetreten?"
  • "Welche Services werfen in letzter Zeit mehr Exceptions?"
  • "Zeige mir die Exception-Trends für das Payment-System"

4. search_logs 📋

Search general application logs with filtering capabilities.

Parameters:

  • environment (optional): The environment to search in
  • message (optional): Filter by log message content
  • service (optional): Filter by service name
  • timeRange (optional): Time range for search (defaults to last 1 hour)

Use Cases:

  • "Zeige mir alle Logs vom User-Service der letzten Stunde"
  • "Suche nach Logs mit 'payment failed'"

5. test_connection 🔌

Test Elasticsearch connection for a team and environment.

Parameters:

  • environment (optional): The environment to test

Use Cases:

  • "Teste die Verbindung zu Production"
  • "Ist Elasticsearch erreichbar?"

🚀 Common Prompts & Use Cases

Exception Investigation

"Welche Exceptions sind in den letzten 24h häufiger aufgetreten?"
→ Uses: analyze_trends with analysisType="exceptions"

"Mir ist diese Exception 'OutOfMemoryError' aufgefallen, finde mehr über sie heraus"
→ Uses: analyze_exception with exceptionMessage="OutOfMemoryError"

"Welche Exceptions passen zu diesem API-Endpoint /users/profile?"
→ Uses: search_exceptions with query="/users/profile"

Service Health Monitoring

"Welche Services werfen in letzter Zeit mehr Exceptions?"
→ Uses: analyze_trends with analysisType="services"

"Zeige mir alle Exceptions vom Payment-Service der letzten 6 Stunden"
→ Uses: search_exceptions with service="payment-service" and timeframe="6h"

Debugging & Troubleshooting

"Suche nach Database-Connection-Errors der letzten 24h"
→ Uses: search_exceptions with query="database connection" and timeframe="24h"

"Analysiere die häufigsten Exceptions im User-Service"
→ Uses: search_exceptions with service="user-service" and sortByFrequency=true

🛠️ Development

Code Quality

This project maintains high code quality standards:

# Run all quality checks
npm run check

# Individual checks
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint code analysis
npm run format:check # Prettier formatting check

# Auto-fix issues
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier

Building

# Build the project
npm run build

# Clean build artifacts
npm run clean

Scripts Overview

  • npm run dev - Start development server with hot reload
  • npm run build - Build for production
  • npm run start - Build and start production server
  • npm run cli - Run the CLI tool
  • npm run check - Run all quality checks

Architecture

The server is built with a modular architecture:

  • ConfigManager: Handles team configuration loading and validation
  • ElasticsearchService: Manages Elasticsearch connections and queries
  • MCP Tools: Individual tools for different operations (5 optimized tools)
  • HTTP Server: Provides HTTP+SSE transport for web interfaces
  • STDIO Transport: Provides STDIO transport for MCP clients

Tool Design Philosophy

The tools are designed with these principles:

  • Short, memorable names (11-17 characters)
  • Clear separation of concerns (search vs. analyze vs. trends)
  • Flexible parameters to support various use cases
  • No functional duplication between tools

Security Considerations

  • Store sensitive credentials (API keys, passwords) securely
  • Use environment variables for sensitive configuration
  • Consider network security for Elasticsearch connections
  • Implement proper access controls per team
  • Use the allowedOperations configuration to restrict team capabilities

Error Handling

The server includes comprehensive error handling:

  • Configuration validation on startup
  • Connection error handling with retries
  • Graceful degradation for unavailable services
  • Detailed logging for troubleshooting

License

MIT

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Run linting and formatting
  6. Submit a pull request