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.

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.