Skip to main content
Glama
openobserve-mcp

openobserve-mcp

by devShahriar

openobserve-mcp

An MCP server that lets any MCP client — Claude Code, Cursor, a custom agent — query an OpenObserve instance: logs, traces, and metrics.

Quick start

npm install
npm run build

npm run o2:up     # OpenObserve on http://localhost:5080
npm run seed      # sample logs, traces, and metrics
npm run smoke     # call every tool over a real stdio MCP session

npm run smoke should print eight ok lines. Log in to the UI at http://localhost:5080 with root@example.com / Complexpass#123.

Related MCP server: otel-mcp

Connecting a client

Claude Code

claude mcp add openobserve \
  --env O2_URL=http://localhost:5080 \
  --env O2_ORG=default \
  --env O2_USER=root@example.com \
  --env O2_PASSWORD='Complexpass#123' \
  -- node /absolute/path/to/openobserve-mcp/dist/index.js

Restart the client afterwards — MCP servers are loaded at session start.

Any client (JSON config)

{
  "mcpServers": {
    "openobserve": {
      "command": "node",
      "args": ["/absolute/path/to/openobserve-mcp/dist/index.js"],
      "env": {
        "O2_URL": "http://localhost:5080",
        "O2_ORG": "default",
        "O2_USER": "root@example.com",
        "O2_PASSWORD": "Complexpass#123"
      }
    }
  }
}

Configuration

Variable

Default

Purpose

O2_URL

http://localhost:5080

Base URL of the instance

O2_ORG

default

Organization id

O2_USER

—

Login email

O2_PASSWORD

—

Password

See .env.example. Credentials are read from the process environment only; nothing is written to disk.

Tools

Tool

Purpose

list_streams

Enumerate streams, optionally filtered by type

get_schema

Field names and types for a stream

get_org_summary

Stream count, storage, pipelines, alerts, dashboards

search_logs

Rows matching a SQL WHERE clause, newest first

aggregate_logs

COUNT / AVG / GROUP BY over logs, traces, or metrics

search_traces

Recent traces with root operation, duration, services

get_trace

Every span of one trace, ordered by start time

query_metrics

PromQL over a time range

Time ranges

Every time argument takes an ISO timestamp or relative shorthand: 30s, 15m, 2h, 7d, 1w. end_time defaults to now.

aggregate_logs table token

Write the table as the literal token stream; it is substituted with the real stream name in FROM / JOIN position only, so a column or string literal containing the word is left alone.

{
  "stream": "app_logs",
  "sql": "SELECT service, COUNT(*) AS c FROM stream GROUP BY service ORDER BY c DESC",
  "start_time": "1h"
}

Logs and traces live in separate indexes. To aggregate spans, pass "stream_type": "traces" — otherwise OpenObserve reports stream not found.

Layout

src/
  index.ts          entrypoint — stdio transport only
  server.ts         builds a wired McpServer (importable for tests)
  config.ts         environment → Config
  client.ts         OpenObserve HTTP API wrapper
  time.ts           ISO / relative range parsing → micros + seconds
  tools/
    index.ts        registers every tool
    helpers.ts      JSON result shape, SQL quoting, shared schema
    streams.ts      list_streams, get_schema, get_org_summary
    logs.ts         search_logs, aggregate_logs
    traces.ts       search_traces, get_trace
    metrics.ts      query_metrics
scripts/
  seed.mjs          sample logs, traces, metrics
  smoke.mjs         stdio MCP client — exercises every tool
docker-compose.yml  local OpenObserve

Adding a tool means one file in src/tools/ plus a line in src/tools/index.ts.

Verified against

OpenObserve public.ecr.aws/zinclabs/openobserve:latest (v0.15.x), MCP SDK 1.25, Node 22.

Endpoint paths are version-sensitive. Two in particular differ from what the API docs suggest: stream schema is /api/{org}/streams/{stream}/schema (not /api/{org}/{stream}/schema), and there is no /traces/{trace_id} endpoint — get_trace searches the trace stream by id instead. If you upgrade OpenObserve, re-run npm run smoke.

Development

npm run watch      # tsc --watch
npm run smoke      # regression check against a live instance
node scripts/smoke.mjs list                    # inspect registered tools
node scripts/smoke.mjs get_schema '{"stream":"app_logs"}'

scripts/smoke.mjs speaks the real MCP protocol over stdio, so it catches schema and transport regressions that a direct HTTP test would miss.

Available Tools

8 tools
aggregate_logsA

Run an aggregation query (COUNT, AVG, SUM, GROUP BY). Write the table name as stream and it is substituted with the real stream.

Inputs: sql (required), stream (required), start_time (required), end_time, +1 more.

get_org_summaryA

Get organization summary: stream count, storage, pipelines, alerts, dashboards

Inputs: no named parameters.

get_schemaA

Get the field names and types for a stream

Inputs: stream (required), stream_type.

get_traceA

Get every span of a single trace, ordered by start time

Inputs: trace_id (required), start_time (required), stream, end_time.

list_streamsA

List available streams (logs, metrics, traces) in OpenObserve

Inputs: stream_type.

query_metricsA

Query metrics with PromQL over a time range (Prometheus query_range)

Inputs: query (required), start_time (required), step, end_time.

search_logsA

Search logs with an optional SQL WHERE clause, newest first

Inputs: stream (required), start_time (required), limit, query, +1 more.

search_tracesA

List recent traces with their root operation, duration, and participating services

Inputs: start_time (required), limit, filter, stream, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of OpenObserve: streams, schema, org summary, logs, traces, metrics. Search vs. aggregate vs. query are clearly differentiated by descriptions, and search_traces vs. get_trace are separate listing vs. detail operations.

    Naming Consistency5/5

    All tool names use snake_case with a verb_noun structure (list_, get_, search_, aggregate_, query_). The verbs accurately reflect the operation, and the nouns denote the target resource. This is highly predictable.

    Tool Count5/5

    With 8 tools covering streams, schema, logs, traces, and metrics, the surface is well-scoped without being bloated. Each tool fills a necessary role for an observability MCP server.

    Completeness5/5

    The set provides a comprehensive read-only query surface: listing streams, inspecting schemas, searching and aggregating logs, listing traces with details, and querying metrics. No obvious dead ends or missing critical operations for the core domain.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A read-only MCP server for OpenObserve Community Edition that works over the REST API. Provides tools for searching logs, traces, stream schemas, and dashboards - no Enterprise license required.
      8
      73 PyPI
      16
      GPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that gives AI agents access to your application's OpenTelemetry traces for querying, analysis, and debugging.
      5
      11 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI assistants to query and explore your OpenObserve observability data. Provides read-only access to logs, metrics, and traces for analysis and troubleshooting.
      5
      MIT