OpenObserve MCP Server

A Model Context Protocol (MCP) server for querying multiple OpenObserve instances. Adaptive query strategies, batch execution, cursor pagination, and LRU caching over a stdio transport.

Source: https://github.com/adarshba/openobserve-mcp

What is this?

Exposes OpenObserve log, trace, and metrics querying as MCP tools. An AI agent (Claude, Cursor, OpenCode, etc.) connects over stdio and calls tools to search logs, inspect stream schemas, and fetch contextual records across one or many OpenObserve instances simultaneously.

Quick Start

npm install npm run build

export PROD_O2_TOKEN=$(echo -n “[email protected]:password” | base64) node dist/index.js --config ./config/openobserve.config.json

Configuration

Edit config/openobserve.config.json. Each instance entry requires:

id - unique identifier used in tool calls name - human-readable label url - base URL of the OpenObserve instance auth - references an environment variable holding a Base64 token defaults - org, timeout, maxResults capabilities - subset of: logs, traces, metrics tags - arbitrary labels for filtering (e.g. production, staging, gcp)

Top-level options:

batching.maxConcurrent - max concurrent queries (default: 5) batching.maxBatchSize - max queries per batch (default: 100) caching.enabled - enable LRU query cache (default: true) caching.ttl - cache TTL in seconds (default: 300) caching.maxSize - max cached entries (default: 1000)

Auth Token

Each instance authenticates with a Base64-encoded “username:password” string passed via environment variable. Never put credentials directly in the config.

export PROD_O2_TOKEN=$(echo -n “[email protected]:secretpass” | base64)

The config references the env var name:

“auth”: { “type”: “env”, “envVar”: “PROD_O2_TOKEN” }

Config path can also be provided via environment variable:

O2_MCP_CONFIG_PATH=./config/openobserve.config.json npx openobserve-mcp

Or pass the full config JSON inline:

O2_MCP_CONFIG=‘{“instances”:[…]}’ npx openobserve-mcp

MCP Client Setup

Add to your MCP client config (Claude Desktop, Cursor, OpenCode, etc.):

{ “mcpServers”: { “openobserve”: { “command”: “npx”, “args”: [“openobserve-mcp”, “–config”, “/path/to/config.json”], “env”: { “PROD_O2_TOKEN”: “your_base64_token” } } } }

Tools

search_logs Search logs with SQL across one or more instances. Automatically selects the most efficient strategy based on time range: ≤1 h raw fetch (capped at 200 rows, paginated) 1–6 h reservoir sampling (recent, diverse, or error-biased) 6 h–7 d hourly histogram aggregation >7 d daily histogram aggregation

instances (required) array of instance IDs