Jamsheed-CS/mcp-server-elasticsearch-mcpo

Elasticsearch MCP Server (MCPO-ready)

This repository provides an MCP (Model Context Protocol) server for Elasticsearch and includes an MCPO wrapper to expose the server as standard OpenAPI/REST endpoints for consumption by web UIs like OpenWebUI.

Key features:

• MCP transports: stdio, streamable-HTTP and SSE (SSE is deprecated)
• MCPO wrapper: convert MCP servers to OpenAPI using mcpo (recommended for web & cloud use)
• Docker and Docker Compose files to run the MCPO-wrapped server

This README has been simplified to focus on running the server with MCPO. For advanced configuration see the in-repo examples and deploy.sh.

Quick start (MCPO)

1. Copy the example env file and edit your Elasticsearch connection:

cp .env.example .env
# Edit .env and set ES_URL and credentials

2. Start with Docker Compose (recommended):

./deploy.sh deploy

3. Open the generated OpenAPI docs:

• Interactive docs: http://localhost:8000/docs
• OpenAPI spec: http://localhost:8000/openapi.json

Manual Docker (build & run)

Build and run the MCPO image locally:

docker build -f Dockerfile-mcpo -t elasticsearch-mcpo .
docker run -d \
  --name elasticsearch-mcpo \
  -p 8000:8000 \
  -e ES_URL="https://your-elasticsearch:9200" \
  -e ES_API_KEY="your_api_key" \
  elasticsearch-mcpo

What MCPO does

mcpo runs the MCP server as a subprocess, discovers MCP tools at startup, and auto-generates REST endpoints and OpenAPI documentation. This makes the MCP server instantly usable by OpenWebUI and any OpenAPI client.

Environment variables

• ES_URL (required): Elasticsearch cluster URL
• ES_API_KEY OR ES_USERNAME/ES_PASSWORD (required): Authentication
• ES_SSL_SKIP_VERIFY (optional): Skip TLS verification (use with caution)
• MCPO_HOST (optional): MCPO bind address (default: 0.0.0.0)
• MCPO_PORT (optional): MCPO port (default: 8000)

Deployment helper

Use deploy.sh for building, deploying, testing and stopping the service. Run ./deploy.sh help for usage.

Next steps / Testing

• After deployment, visit /docs to confirm OpenAPI was generated.
• Integrate with OpenWebUI by adding the MCPO base URL (http://<host>:<port>) as an external endpoint in OpenWebUI settings.

For any additional configuration or advanced usage, consult the source files and the docker-compose.yml and Dockerfile-mcpo in this repository.

MCPO (MCP-to-OpenAPI) for OpenWebUI Integration

This server also supports MCPO (MCP-to-OpenAPI proxy), which converts the MCP server into standard REST/OpenAPI endpoints. This is ideal for integrating with OpenWebUI and other OpenAPI-compatible tools.

Why Use MCPO?

• Web UI Compatibility: Instantly compatible with OpenWebUI and other web interfaces
• Standard REST APIs: Exposes familiar HTTP endpoints instead of custom MCP protocols
• Auto-generated Documentation: Interactive OpenAPI/Swagger documentation at /docs
• Cloud Deployment: Easy to deploy and scale in cloud environments
• No Custom Clients: Works with any HTTP client, curl, or OpenAPI SDK

Quick Start with MCPO

Using Docker Compose (Recommended)

1. Clone and setup:

   git clone https://github.com/elastic/mcp-server-elasticsearch.git
   cd mcp-server-elasticsearch
   cp .env.example .env
   

2. Configure your environment (edit .env):

   ES_URL=https://your-elasticsearch-cluster.com:9200
   ES_API_KEY=your_api_key_here
   

3. Deploy:

   ./deploy.sh deploy
   

4. Access OpenAPI documentation:

   • Interactive docs: http://localhost:8000/docs
   • OpenAPI spec: http://localhost:8000/openapi.json

Manual Docker Build

# Build the MCPO image
docker build -f Dockerfile-mcpo -t elasticsearch-mcpo .

# Run the service
docker run -d \
  --name elasticsearch-mcpo \
  -p 8000:8000 \
  -e ES_URL="https://your-elasticsearch.com:9200" \
  -e ES_API_KEY="your_api_key" \
  elasticsearch-mcpo

Using Pre-built Images

# Pull and run (when available on Docker Hub)
docker run -d \
  --name elasticsearch-mcpo \
  -p 8000:8000 \
  -e ES_URL="https://your-elasticsearch.com:9200" \
  -e ES_API_KEY="your_api_key" \
  elastic/elasticsearch-mcpo:latest

OpenWebUI Integration

Once your MCPO service is running, you can integrate it with OpenWebUI:

1. In OpenWebUI Admin Panel:

   • Go to Admin Panel → Settings → External → Endpoints
   • Add a new endpoint with URL: http://localhost:8000
   • The tools will be automatically discovered via OpenAPI

2. Environment Variables for OpenWebUI:

   OPENWEBUI_EXTERNAL_ENDPOINTS="http://localhost:8000"
   

Available REST Endpoints

When running with MCPO, the following REST endpoints are automatically generated:

• POST /list_indices - List all Elasticsearch indices
• POST /get_mappings - Get field mappings for an index
• POST /search - Perform Elasticsearch queries
• POST /esql - Execute ES|QL queries
• POST /get_shards - Get shard information

Each endpoint includes full OpenAPI documentation with request/response schemas.

Production Deployment

For production deployments, see the deployment script options:

# Show all deployment options
./deploy.sh help

# Deploy with custom configuration
./deploy.sh deploy-manual latest 8080

# Check service status
./deploy.sh status

# Test the deployment
./deploy.sh test

Environment Variables

All the same environment variables from the standard MCP server apply:

• ES_URL (required): Elasticsearch cluster URL
• ES_API_KEY or ES_USERNAME/ES_PASSWORD (required): Authentication
• ES_SSL_SKIP_VERIFY (optional): Skip SSL verification
• MCPO_HOST (optional): MCPO bind address (default: 0.0.0.0)
• MCPO_PORT (optional): MCPO port (default: 8000)