mcp-opensearch

Read-only MCP server for exploring and searching OpenSearch 2 clusters. Ideal for log analysis, index exploration, and query execution.

Tools

Tool	Description
ping	Check connectivity — returns cluster name and version
cluster_health	Cluster health status (green/yellow/red), node and shard counts
list_indices	List indices with health, doc count, and size. Optional pattern filter
get_index_mapping	Show field types and structure for an index
search	Execute queries using OpenSearch Query DSL (JSON)
count	Count documents matching an optional query
list_aliases	List all index aliases
get_document	Retrieve a specific document by ID

Installation — Claude Desktop Extension

1. Build the extension package:

npx @anthropic-ai/mcpb pack .

2. In Claude Desktop, go to Settings → Extensions and upload mcpopensearch.mcpb.

3. Configure via the UI:

   • OpenSearch URL — e.g. http://your-opensearch:9200
   • Username / Password — optional, for basic auth

Installation — Claude Code

Add to your .claude/settings.json:

{
  "mcpServers": {
    "opensearch": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcpopensearch", "run", "server.py"],
      "env": {
        "OPENSEARCH_URL": "http://localhost:9200",
        "OPENSEARCH_USERNAME": "",
        "OPENSEARCH_PASSWORD": ""
      }
    }
  }
}

Environment Variables

Variable	Default	Description
OPENSEARCH_URL	http://localhost:9200	OpenSearch cluster URL
OPENSEARCH_USERNAME	(none)	Basic auth username
OPENSEARCH_PASSWORD	(none)	Basic auth password

Query Examples

Search for errors in the last hour:

{
  "query": {
    "bool": {
      "must": [
        {"match": {"level": "ERROR"}},
        {"range": {"@timestamp": {"gte": "now-1h"}}}
      ]
    }
  },
  "sort": [{"@timestamp": "desc"}]
}

Count documents by status code:

{
  "query": {"match_all": {}},
  "aggs": {"status_codes": {"terms": {"field": "response_code"}}}
}

License

MIT