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
sql (required) SQL query string
startTime (required) ISO 8601 or Unix ms
endTime (required) ISO 8601 or Unix ms
limit results per instance (raw strategy only), default 100
trackTotalHits compute exact total count, slower on large streams
cursor pagination cursor from a previous response
bypassCache skip cache and force fresh fetch

batch_query
Execute multiple independent SQL queries in parallel. Each query targets
a specific instance. Partial failures are isolated.

queries[].instanceId (required) target instance ID
queries[].sql (required) SQL query
queries[].startTime (required) start time
queries[].endTime (required) end time
queries[].limit result limit, default 100

list_instances
List all configured instances. Optionally filter by tag or capability.

tags filter by any matching tag
capability filter by capability: logs, traces, or metrics

list_streams
List available streams from one or more instances in parallel.

instances (required) array of instance IDs

get_stream_schema
Return field names and types for one or more streams. Results are cached
for 10 minutes.

instance (required) instance ID
streams (required) stream name or array of stream names

get_logs_around
Fetch log records surrounding a specific timestamp without writing SQL.
Useful for viewing context around a known event.

instance (required) instance ID
stream (required) stream name
timestamp (required) anchor timestamp (ISO 8601 or Unix ms)
size total records to return, default 20

SQL Reference

OpenObserve uses a PostgreSQL-compatible SQL dialect.

_timestamp built-in time field; always present
match_all('text') full-text search across indexed fields (wildcard: *)
str_match(field, 'x') text match on a specific field
histogram(_timestamp, '1 hour') time-bucketed aggregation

Do not add WHERE _timestamp filters — time range is controlled by
startTime and endTime parameters.

Examples:

SELECT * FROM "mystream" WHERE level = 'error'

SELECT * FROM "mystream" WHERE match_all('payment failed*')

SELECT service, COUNT(*) AS errors
FROM "mystream" WHERE level = 'error'
GROUP BY service ORDER BY errors DESC

SELECT histogram(_timestamp, '1 hour') AS ts, COUNT(*) AS count
FROM "mystream" GROUP BY ts ORDER BY ts

Project Layout

src/index.ts entry point, CLI arg parsing, stdio transport
src/server.ts MCP server, tool registration, response serialization
src/cache.ts LRU cache with TTL and SHA-256 key generation
src/tracing.ts optional Langfuse tracing wrapper
src/config/schema.ts Zod schemas for config, API responses, and tool inputs
src/config/loader.ts config loader and environment variable resolution
src/client/instance.ts HTTP client for a single OpenObserve instance
src/client/pool.ts manages the set of all configured instances
src/types/config.ts server and instance configuration types
src/types/query.ts query, result, and strategy types
src/types/tools.ts tool result types
src/types/index.ts barrel export for all types
src/query/analyzer.ts SQL intent detection (aggregates, error filters)
src/query/rewriter.ts rewrites SELECT queries to histogram aggregation SQL
src/query/sampler.ts reservoir sampling (recent, diverse, errors modes)
src/query/router.ts selects query strategy from time range and SQL intent
src/query/strategies/aggregate.ts time-bucketed count strategy
src/query/strategies/sample.ts reservoir-sampled rows strategy
src/query/strategies/raw.ts passthrough strategy capped at 200 rows
src/tools/search-logs.ts search_logs handler
src/tools/batch-query.ts batch_query handler
src/tools/list-instances.ts list_instances handler
src/tools/list-streams.ts list_streams handler
src/tools/get-stream-schema.ts get_stream_schema handler
src/tools/get-logs-around.ts get_logs_around handler
src/utils/time.ts timestamp parsing utility

Optional: Langfuse Tracing

Set these environment variables to emit traces to Langfuse:

LANGFUSE_O2_ENABLED set to "true" to enable
LANGFUSE_O2_PUBLIC_KEY Langfuse project public key
LANGFUSE_O2_SECRET_KEY Langfuse project secret key
LANGFUSE_O2_BASE_URL Langfuse host (default: https://cloud.langfuse.com)

License

MIT