Overview

The OpenSearch MCP Server is a lightweight Python service that exposes OpenSearch indices as MCP (Model Context Protocol) tools so AI agents can query, analyze, and retrieve data directly from your OpenSearch cluster. By presenting search and analytics operations as standardized MCP tools, agents (and orchestration layers) can request contextual data, run aggregations, or execute SQL queries against indices in a consistent, programmatic way.

This approach is useful for building retrieval-augmented workflows, automated analytics agents, and observability or security assistants that need low-latency access to indexed data. The server handles connection management, authentication, and request translation between MCP tool calls and OpenSearch APIs so developers can focus on agent logic rather than cluster plumbing.

Features

Exposes OpenSearch indices as MCP-compatible tools for AI agents
Support for Query DSL search and SQL-style analytics (when enabled on your cluster)
Fetch documents by ID and run aggregations for fast metrics
Configurable authentication (basic auth and TLS) and connection settings
Docker-friendly and simple to run locally for development
Lightweight Python implementation suitable for embedding into ML/agent stacks

Installation / Configuration

Prerequisites: Python 3.8+ and an accessible OpenSearch cluster.

Clone and install:

git clone https://github.com/opensearch-project/opensearch-mcp-server-py.git
cd opensearch-mcp-server-py
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment variables (recommended) — a common set used by the server:

OPENSEARCH_HOST=opensearch.example.com
OPENSEARCH_PORT=9200
OPENSEARCH_USER=admin
OPENSEARCH_PASSWORD=admin
OPENSEARCH_USE_SSL=true
MCP_BIND_HOST=0.0.0.0
MCP_BIND_PORT=8080
LOG_LEVEL=info
INDEX_PREFIX=

Example .env:

OPENSEARCH_HOST=localhost
OPENSEARCH_PORT=9200
OPENSEARCH_USER=admin
OPENSEARCH_PASSWORD=admin
OPENSEARCH_USE_SSL=false
MCP_BIND_HOST=0.0.0.0
MCP_BIND_PORT=8080

Run the server (development):

# Using uvicorn to run the FastAPI app (common pattern)
uvicorn main:app --host ${MCP_BIND_HOST} --port ${MCP_BIND_PORT} --reload

Docker example:

# Dockerfile (basic)
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8080
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

Run:

docker build -t opensearch-mcp .
docker run --env-file .env -p 8080:8080 opensearch-mcp

Configuration file (optional YAML) — example keys you may see:

opensearch:
  host: "localhost"
  port: 9200
  use_ssl: false
  user: "admin"
  password: "admin"
mcp:
  bind_host: "0.0.0.0"
  bind_port: 8080
logging:
  level: "INFO"

Available Resources

The server exposes OpenSearch functionality as MCP tools that agents can call. Typical resources and operations include:

Search tool: run a Query DSL request against one or more indices
SQL tool: submit SQL or PPL statements to the cluster (if SQL plugin enabled)
Get document: fetch a document by index and ID
Aggregations: run metric and bucket aggregations for analytics
Index metadata: list indices and mappings (useful for tool description)

Example resource types presented to agents:

indices (names, mappings)
documents (JSON source)
metrics (aggregation results)

Note: The exact tool names and API paths may vary by server release; consult the running server’s /describe or /tools endpoint for the canonical list of tools it exposes.

Quick examples

Search with Query DSL (curl):

curl -X POST "http://localhost:8080/tools/search" \
  -H "Content-Type: application/json" \
  -d '{
    "indices": ["logs-*"],
    "query": {
      "match": {"message": "error"}
    },
    "size": 5
  }'

SQL query (curl):

curl -X POST "http://localhost:8080/tools/sql" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT count(*) as errors, date_trunc(\'hour\', @timestamp) as hour FROM logs-* WHERE level = \'error\' GROUP BY hour ORDER BY hour DESC LIMIT 24"
  }'

Fetch a document by ID:

curl -X GET "http://localhost:8080/tools/get?index=my-index&id=abc123"

These endpoints return JSON payloads formatted for MCP tool responses so agents can easily consume results.

Use Cases

Retrieval-Augmented

OpenSearch MCP Server for AI Search and Analytics