sonirico/mcp-elasticsearch
If you are the rightful owner of mcp-elasticsearch 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 MCP Elasticsearch Server provides a standardized interface for querying Elasticsearch clusters, enabling seamless integration with AI assistants and other MCP clients.
MCP Elasticsearch Server π
A Model Context Protocol (MCP) server that provides Elasticsearch integration capabilities to AI assistants and other MCP clients. This server enables querying Elasticsearch clusters through a standardized interface.
Features
- π Multiple Authentication Methods: Supports both API key and username/password authentication
- π Index Management: List indices with health status and document counts
- πΊοΈ Schema Discovery: Retrieve field mappings to understand index structure
- π Advanced Search: Execute complex Elasticsearch queries with aggregations and sorting
- π Structured Responses: JSON-formatted output with search metadata
- β‘ Performance Monitoring: Query execution time tracking
- π― Context Aware: Supports search execution with proper context cancellation
Tools
list_indices
List all Elasticsearch indices with optional pattern filtering.
Parameters:
pattern
(string, optional): Index pattern filter (default: "*")
Returns:
- Total index count
- Index details (name, health, status, document count, size)
get_index_mappings
Get field mappings for one or more Elasticsearch indices.
Parameters:
index
(string, required): Index name or pattern
Returns:
- Complete field mappings for the specified indices
search
Execute Elasticsearch search queries with full DSL support.
Parameters:
index
(string, required): Index name or pattern to searchquery
(string, optional): Elasticsearch query DSL as JSON (default: "{}")size
(number, optional): Maximum documents to return (default: 10, max: 10000)sort
(string, optional): Sort specification as JSONtrack_total_hits
(boolean, optional): Track total hit count (default: true)
Returns:
- Search results with hits, aggregations, and metadata
Configuration
Environment Variables
Elasticsearch Configuration
ES_URL
: Elasticsearch cluster URL (required)ES_API_KEY
: API key for authentication (optional)ES_USERNAME
: Username for basic authentication (optional)ES_PASSWORD
: Password for basic authentication (optional)
Server Configuration
MCP_ES_SERVER_NAME
: Server name (default: "mcp-elasticsearch π")
Logging Configuration
MCP_ES_LOG_LEVEL
: Log level (debug, info, warn, error, fatal)MCP_ES_LOG_FORMAT
: Log format (json, console)MCP_ES_LOG_OUTPUT
: Log output (stdout, stderr)
Authentication
You must provide either:
- API Key authentication: Set
ES_API_KEY
- Basic authentication: Set both
ES_USERNAME
andES_PASSWORD
Installation
# Clone and build
git clone <repository>
cd mcp-elasticsearch
go mod download
go build -o bin/mcp-elasticsearch .
# Install to system
sudo install bin/mcp-elasticsearch /usr/local/bin/
Usage
Direct Execution
# With API key
ES_URL="https://your-cluster.com" ES_API_KEY="your-api-key" mcp-elasticsearch
# With basic auth
ES_URL="https://your-cluster.com" ES_USERNAME="user" ES_PASSWORD="pass" mcp-elasticsearch
# With custom logging
ES_URL="https://your-cluster.com" ES_API_KEY="key" MCP_ES_LOG_LEVEL=debug mcp-elasticsearch
Integration with Claude Desktop
Add to your Claude configuration:
{
"mcpServers": {
"elasticsearch": {
"command": "mcp-elasticsearch",
"env": {
"ES_URL": "https://your-cluster.com",
"ES_API_KEY": "your-api-key",
"MCP_ES_LOG_LEVEL": "info"
}
}
}
}
Integration with ApMentor
Update your config.json
:
{
"mcpServers": {
"elasticsearch-go": {
"command": "/usr/local/bin/mcp-elasticsearch",
"env": {
"ES_URL": "https://atani.es.eu-west-1.aws.found.io",
"ES_API_KEY": "your-api-key",
"MCP_ES_LOG_LEVEL": "info"
}
}
}
}
Example Queries
List All Indices
{
"tool": "list_indices",
"parameters": {
"pattern": "*"
}
}
List Log Indices Only
{
"tool": "list_indices",
"parameters": {
"pattern": "logs-*"
}
}
Get Index Mappings
{
"tool": "get_index_mappings",
"parameters": {
"index": "logs-apm.error-*"
}
}
Simple Search
{
"tool": "search",
"parameters": {
"index": "logs-*",
"query": "{\"match\": {\"service.name\": \"broker-api-b2b\"}}",
"size": 50
}
}
Complex Search with Aggregations
{
"tool": "search",
"parameters": {
"index": "logs-*",
"query": "{\"bool\": {\"must\": [{\"term\": {\"service.name\": \"broker-api-b2b\"}}, {\"range\": {\"@timestamp\": {\"gte\": \"now-24h\"}}}]}}",
"size": 0,
"aggs": "{\"error_types\": {\"terms\": {\"field\": \"error.type.keyword\", \"size\": 10}}}"
}
}
Search with Sorting
{
"tool": "search",
"parameters": {
"index": "logs-*",
"query": "{\"match\": {\"log.level\": \"ERROR\"}}",
"sort": "[{\"@timestamp\": {\"order\": \"desc\"}}]",
"size": 20
}
}
Development
# Install dependencies
go mod download
# Format code
gofmt -w .
# Run tests
go test -v ./...
# Build
go build -o bin/mcp-elasticsearch .
# Run with debug logging
MCP_ES_LOG_LEVEL=debug go run .
Error Handling
The server provides detailed error messages for common issues:
- Authentication failures: Check your API key or credentials
- Index not found: Verify index names and patterns
- Query syntax errors: Validate your Elasticsearch query JSON
- Connection issues: Ensure Elasticsearch is accessible
Security Considerations
- Store API keys and credentials securely
- Use environment variables for sensitive configuration
- Consider network security for Elasticsearch access
- Monitor query patterns and resource usage
License
MIT License - See LICENSE file for details.