openobserve-community-mcp
This is a read-only MCP server for OpenObserve Community Edition that enables querying and analysis of logs, traces, dashboards, and stream metadata via the OpenObserve REST API from local MCP clients like Claude and Codex.
list_streams: Browse available streams in your organization, filterable by keyword and stream type, with sorting and pagination support.get_stream_schema: Retrieve field/schema information for a specific stream, with a configurable limit on fields to inspect.search_logs: Run SQL queries against logs supporting WHERE, ORDER BY, GROUP BY, and aggregate functions. Includes token-efficient output formats (recordsorcolumns) and Kubernetes-compact record profiles.search_around: Fetch log records surrounding a specific entry by its_timestampvalue for contextual investigation.search_values: Discover distinct field values for a stream over a time range, with optional filtering and keyword search.list_dashboards: List all dashboards in your organization, with optional filtering by title or folder.get_dashboard: Retrieve the full definition of a specific dashboard by its ID.get_latest_traces: Fetch the most recent trace data from a trace stream within a given time range, with optional filtering.
Supports basic and bearer authentication, optional organization specification, SSL verification control, timeout settings, and multiple deployment options (uvx, local binary, or Docker).
OpenObserve MCP
stdio MCP server for OpenObserve Community Edition, using only the regular REST API.
This package is designed for local MCP clients such as Claude and Codex.
What it is:
stdioonlyCommunity Edition only
read-only only
regular OpenObserve REST API only
no native
/mcpendpoint
The server can boot without an active OpenObserve configuration so hosted MCP platforms can start it,
but every tool call still requires a reachable external OpenObserve instance configured via OO_BASE_URL
and credentials.
Quick Start
1. Create a config file
uvx --from openobserve-community-mcp openobserve-mcp init-configThis creates a sample config at:
~/.config/openobserve-mcp/config.envEdit it:
vim ~/.config/openobserve-mcp/config.envExample:
OO_BASE_URL=https://openobserve.example.com
# Optional if the credentials have access to exactly one organization.
# OO_ORG_ID=default
OO_AUTH_MODE=basic
OO_USERNAME=your_username
OO_PASSWORD=your_password
OO_TIMEOUT_SECONDS=20
OO_VERIFY_SSL=true2. Add it to Claude
claude mcp add -s user openobserve-community -- uvx --from openobserve-community-mcp openobserve-mcp3. Add it to Codex
codex mcp add openobserve-community -- uvx --from openobserve-community-mcp openobserve-mcp4. Add it to OpenCode
OpenCode configures MCP servers under mcp in its config file. According to the official docs,
you can add MCP servers in your global config at ~/.config/opencode/opencode.json or in a
project-level opencode.json.
See:
If you created the sample config with openobserve-mcp init-config, you can point OpenCode to it:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"openobserve-community": {
"type": "local",
"command": ["uvx", "--from", "openobserve-community-mcp", "openobserve-mcp"],
"enabled": true,
"environment": {
"OO_CONFIG_FILE": "/absolute/path/to/config.env"
}
}
}
}You can also inline the OpenObserve settings directly in the OpenCode MCP config:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"openobserve-community": {
"type": "local",
"command": ["uvx", "--from", "openobserve-community-mcp", "openobserve-mcp"],
"enabled": true,
"environment": {
"OO_BASE_URL": "https://openobserve.example.com",
"OO_AUTH_MODE": "basic",
"OO_USERNAME": "your_username",
"OO_PASSWORD": "your_password"
}
}
}
}OpenCode's MCP docs also support optional enabled, environment, and timeout fields for local
servers if you want to tune startup behavior.
Related MCP server: OpenTelemetry MCP Server
Docker / Glama
This repository also publishes a container image for Docker-based MCP clients and Glama deployments:
docker run --rm -i \
-e OO_BASE_URL \
-e OO_ORG_ID \
-e OO_AUTH_MODE \
-e OO_USERNAME \
-e OO_PASSWORD \
-e OO_TOKEN \
-e OO_TIMEOUT_SECONDS \
-e OO_VERIFY_SSL \
ghcr.io/alilxxey/openobserve-community-mcp:latestOO_ORG_ID is optional when the credentials only have access to one organization.
Use OO_USERNAME and OO_PASSWORD for basic auth, or OO_TOKEN for bearer auth.
The container can start without these values for hosted MCP platforms, but tool calls will fail until
you configure a real external OpenObserve instance.
Configuration
Default config path:
~/.config/openobserve-mcp/config.envSupported settings:
OO_BASE_URLOO_ORG_IDoptionalOO_AUTH_MODEOO_USERNAMEandOO_PASSWORDfor basic authOO_TOKENfor bearer authOO_TIMEOUT_SECONDSOO_VERIFY_SSLOO_CONFIG_FILEoptional explicit path to a config file
Config precedence:
explicit
OO_CONFIG_FILE~/.config/openobserve-mcp/config.envlegacy
.env.localin the current directoryprocess environment overrides file values
You can also pass config directly via MCP client env settings.
Claude with inline env
claude mcp add -s user openobserve-community \
-e OO_BASE_URL=https://openobserve.example.com \
-e OO_AUTH_MODE=basic \
-e OO_USERNAME=your_username \
-e OO_PASSWORD=your_password \
-- uvx --from openobserve-community-mcp openobserve-mcpCodex with inline env
codex mcp add openobserve-community \
--env OO_BASE_URL=https://openobserve.example.com \
--env OO_AUTH_MODE=basic \
--env OO_USERNAME=your_username \
--env OO_PASSWORD=your_password \
-- uvx --from openobserve-community-mcp openobserve-mcpOpenCode with inline env
If you prefer to keep everything in OpenCode config instead of a separate config.env, use:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"openobserve-community": {
"type": "local",
"command": ["uvx", "--from", "openobserve-community-mcp", "openobserve-mcp"],
"enabled": true,
"environment": {
"OO_BASE_URL": "https://openobserve.example.com",
"OO_AUTH_MODE": "basic",
"OO_USERNAME": "your_username",
"OO_PASSWORD": "your_password"
}
}
}
}Official OpenCode references:
Tools
list_streamsget_stream_schemasearch_logssearch_aroundsearch_valueslist_dashboardsget_dashboardget_latest_traces
Optional Local Install
If you prefer a persistent local binary instead of uvx:
uv tool install openobserve-community-mcpThis installs the openobserve-mcp command into your user-level uv tools directory.
Add To Claude With Global Install
claude mcp add -s user openobserve-community -- openobserve-mcpAdd To Codex With Global Install
codex mcp add openobserve-community -- openobserve-mcpYou can also run the server directly:
openobserve-mcpThis mode may require ~/.local/bin to be present in your PATH.
If openobserve-mcp is not found, either:
add
~/.local/binto yourPATH; oruse the recommended
uvx --from openobserve-community-mcp openobserve-mcplaunch mode instead.
Available Tools
8 toolsget_dashboardB
Get a dashboard definition by id.
Inputs: dashboard_id (required), include_raw. Returns: object
get_latest_tracesB
Get the latest trace data from a trace stream. start_time and end_time accept Unix timestamps in seconds, milliseconds, microseconds, or nanoseconds and are normalized to microseconds.
Inputs: stream_name (required), start_time (required), end_time (required), size, +4 more. Returns: object
get_stream_schemaA
Get schema information for a specific stream. Use this first to confirm real field names before writing SQL; many log streams expose message rather than log. Increase fields_limit to inspect more fields from large schemas.
Inputs: stream_name (required), fields_limit, include_raw. Returns: object
list_dashboardsC
List dashboards in the current organization.
Inputs: folder, title, page_size, include_raw. Returns: object
list_streamsC
List streams available in the current organization.
Inputs: stream_type, keyword, offset, limit, +2 more. Returns: object
search_aroundA
Fetch records around a specific log entry. key accepts Unix timestamps in seconds, milliseconds, microseconds, or nanoseconds for convenience, but the best input is the exact _timestamp returned by search_logs; otherwise OpenObserve may return no nearby rows. output_format can be 'records' or 'columns' for a more token-efficient table shape. record_profile can be 'generic' or 'kubernetes_compact'.
Inputs: stream_name (required), key (required), size, regions, +4 more. Returns: object
search_logsA
Run a full SQL search against OpenObserve logs. Example row query: SELECT _timestamp, message FROM "my_stream" ORDER BY _timestamp DESC LIMIT 20. Example aggregate query: SELECT level, count(*) AS cnt FROM "my_stream" GROUP BY level ORDER BY cnt DESC LIMIT 20. Prefer double quotes around stream names in SQL when in doubt, and confirm actual field names with get_stream_schema instead of assuming a log column. start_time and end_time accept Unix timestamps in seconds, milliseconds, microseconds, or nanoseconds and are normalized to microseconds. The limit parameter sets the API page size; if your OpenObserve/DataFusion setup still complains about ORDER BY without a SQL LIMIT, add an explicit LIMIT to the SQL as well. output_format can be 'records' or 'columns'; 'columns' is especially useful for wide SELECT * queries and can save roughly 35-40% tokens. record_profile can be 'generic' or 'kubernetes_compact'; the Kubernetes compact profile trims common noisy metadata fields such as pod labels and pod IP metadata.
Inputs: sql (required), start_time (required), end_time (required), limit, +6 more. Returns: object
search_valuesA
Get distinct field values for a stream over a time range. stream_name is the raw stream name path segment, for example my_stream; do not quote it like SQL. fields is a comma-separated field list. filter_query uses OpenObserve's _values filter syntax, e.g. kubernetes_pod_namespace=litellm. Simple SQL-like equality such as kubernetes_pod_namespace='litellm' is normalized automatically. start_time and end_time accept Unix timestamps in seconds, milliseconds, microseconds, or nanoseconds and are normalized to microseconds. In this tool, total means the number of field groups returned, not the total number of matching log records.
Inputs: stream_name (required), fields (required), start_time (required), end_time (required), +8 more. Returns: object
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 has a distinct purpose, but search_logs and search_around both target log entries and could be confused without reading descriptions carefully. However, descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern using snake_case, with verbs like get, list, search applied appropriately.
With 8 tools covering dashboards, streams, logs, traces, schema, and values, the count is well-suited for an observability MCP server.
The tool set covers key querying operations but lacks lifecycle management (create/update/delete) for dashboards and streams, and there is no dedicated search_traces tool beyond get_latest_traces.
Maintenance
Related MCP Connectors
Access New Relic observability data through MCP - query metrics, logs, traces, entities, and more
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Cloud hosted Okahu MCP server that helps you manage genAI trace data
Related MCP Servers
AlicenseBqualityFmaintenanceConnects Claude and other MCP clients to Elasticsearch data, allowing users to interact with their Elasticsearch indices through natural language conversations.34,140 npm733Apache 2.0- FlicenseAqualityDmaintenanceEnables AI agents to query Prometheus metrics and Loki logs for intelligent alert investigation and troubleshooting. Provides service discovery, metric querying, log searching, and correlation tools to help identify root causes of issues.9-
- AlicenseAqualityDmaintenanceEnables querying logs, traces, and metrics from multiple OpenObserve instances via MCP tools, with parallel execution, batching, and caching.692 npm11MIT
- AlicenseNot gradedqualityFmaintenanceA read-only MCP server that exposes Quickwit log search and aggregations to LLM clients, enabling natural language log investigation.Apache 2.0