openobserve-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@openobserve-mcp search my app_logs for errors in the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 sessionnpm 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.jsRestart 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 |
|
| Base URL of the instance |
|
| Organization id |
| — | Login email |
| — | Password |
See .env.example. Credentials are read from the process environment only; nothing is written to disk.
Tools
Tool | Purpose |
| Enumerate streams, optionally filtered by type |
| Field names and types for a stream |
| Stream count, storage, pipelines, alerts, dashboards |
| Rows matching a SQL |
|
|
| Recent traces with root operation, duration, services |
| Every span of one trace, ordered by start time |
| 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 OpenObserveAdding 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 toolsaggregate_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
Scored across 8 tools
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.
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.
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.
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
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Cloud hosted Okahu MCP server that helps you manage genAI trace data
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityDmaintenanceA 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.873 PyPI16GPL 3.0
- AlicenseAqualityDmaintenanceMCP server that gives AI agents access to your application's OpenTelemetry traces for querying, analysis, and debugging.511 npm2MIT
- AlicenseNot gradedqualityCmaintenanceAn 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.5MIT
- AlicenseAqualityDmaintenanceMCP server for AI agent observability, providing trace and span logging, search, latency/tokens/cost metrics, and anomaly detection using an in-memory buffer.6MIT