Skip to main content
Glama
openobserve-community-mcp

openobserve-community-mcp

by alilxxey

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.

openobserve-community-mcp MCP server

What it is:

  • stdio only

  • Community Edition only

  • read-only only

  • regular OpenObserve REST API only

  • no native /mcp endpoint

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-config

This creates a sample config at:

~/.config/openobserve-mcp/config.env

Edit it:

vim ~/.config/openobserve-mcp/config.env

Example:

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=true

2. Add it to Claude

claude mcp add -s user openobserve-community -- uvx --from openobserve-community-mcp openobserve-mcp

3. Add it to Codex

codex mcp add openobserve-community -- uvx --from openobserve-community-mcp openobserve-mcp

4. 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:latest

OO_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.env

Supported settings:

  • OO_BASE_URL

  • OO_ORG_ID optional

  • OO_AUTH_MODE

  • OO_USERNAME and OO_PASSWORD for basic auth

  • OO_TOKEN for bearer auth

  • OO_TIMEOUT_SECONDS

  • OO_VERIFY_SSL

  • OO_CONFIG_FILE optional explicit path to a config file

Config precedence:

  1. explicit OO_CONFIG_FILE

  2. ~/.config/openobserve-mcp/config.env

  3. legacy .env.local in the current directory

  4. process 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-mcp

Codex 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-mcp

OpenCode 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_streams

  • get_stream_schema

  • search_logs

  • search_around

  • search_values

  • list_dashboards

  • get_dashboard

  • get_latest_traces

Optional Local Install

If you prefer a persistent local binary instead of uvx:

uv tool install openobserve-community-mcp

This 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-mcp

Add To Codex With Global Install

codex mcp add openobserve-community -- openobserve-mcp

You can also run the server directly:

openobserve-mcp

This mode may require ~/.local/bin to be present in your PATH.

If openobserve-mcp is not found, either:

  • add ~/.local/bin to your PATH; or

  • use the recommended uvx --from openobserve-community-mcp openobserve-mcp launch mode instead.

Available Tools

8 tools
get_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

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, with verbs like get, list, search applied appropriately.

    Tool Count5/5

    With 8 tools covering dashboards, streams, logs, traces, schema, and values, the count is well-suited for an observability MCP server.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      F
      maintenance
      Connects Claude and other MCP clients to Elasticsearch data, allowing users to interact with their Elasticsearch indices through natural language conversations.
      3
      4,140 npm
      733
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables querying logs, traces, and metrics from multiple OpenObserve instances via MCP tools, with parallel execution, batching, and caching.
      6
      92 npm
      11
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      A read-only MCP server that exposes Quickwit log search and aggregations to LLM clients, enabling natural language log investigation.
      Apache 2.0