OpenObserve MCP Server

Model Context Protocol server for querying OpenObserve from AI agents (Claude, Cursor, OpenCode, etc.).

Features

• Multi-instance — query multiple OpenObserve deployments in a single call
• Adaptive strategy — raw fetch ≤1 h, reservoir sampling 1–6 h, hourly aggregation 6 h–7 d, daily aggregation >7 d
• Batch queries — parallel multi-query execution with configurable concurrency
• LRU cache — TTL-based result caching with per-entry size cap
• Cursor pagination — stateless pagination across instances via base64 cursors
• Langfuse tracing — optional observability for every tool call

Installation

npm install -g openobserve-mcp
# or without installing:
npx openobserve-mcp --config /path/to/config.json

Configuration

Create a JSON config file:

{
  "instances": [
    {
      "id": "prod",
      "name": "Production",
      "url": "https://openobserve.example.com",
      "auth": { "type": "env", "envVar": "PROD_O2_TOKEN" },
      "defaults": { "org": "default", "timeout": 30000, "maxResults": 1000 },
      "capabilities": ["logs", "traces", "metrics"],
      "tags": ["production"]
    }
  ],
  "batching": { "maxConcurrent": 5 },
  "caching": { "enabled": true, "ttl": 300, "maxSize": 1000 }
}

auth.envVar must point to an environment variable containing a Base64-encoded user:password string:

export PROD_O2_TOKEN=$(echo -n "[email protected]:password" | base64)

Config can also be passed inline via the O2_MCP_CONFIG environment variable (JSON string).

MCP Client Setup

Claude Desktop / Cursor — add to your MCP config:

{
  "mcpServers": {
    "openobserve": {
      "command": "npx",
      "args": ["openobserve-mcp", "--config", "/path/to/config.json"],
      "env": {
        "PROD_O2_TOKEN": "base64token"
      }
    }
  }
}

OpenCode — add to .opencode/config.json:

{
  "mcp": {
    "openobserve": {
      "type": "local",
      "command": ["npx", "openobserve-mcp", "--config", "/path/to/config.json"],
      "environment": {
        "PROD_O2_TOKEN": "base64token"
      },
      "enabled": true
    }
  }
}

Tools

| Tool | Description | |------|-------------| | search_logs | Search log streams with SQL across one or more instances. Automatically selects query strategy based on time range. | | batch_query | Execute multiple SQL queries in parallel across instances. | | list_instances | List configured instances with their capabilities and tags. | | list_streams | List available streams on one or more instances. | | get_stream_schema | Return field names and types for one or more streams (cached 10 min). | | get_logs_around | Fetch log records surrounding a specific timestamp without writing SQL. |

SQL Reference

-- Basic filter
SELECT * FROM "mystream" WHERE level = 'error'

-- Full-text search
SELECT * FROM "mystream" WHERE match_all('timeout*')

-- Aggregation
SELECT code, COUNT(*) FROM "mystream" GROUP BY code ORDER BY COUNT(*) DESC

-- Time bucketing (do not add _timestamp filters manually)
SELECT histogram(_timestamp, '1 hour') AS ts, COUNT(*) FROM "mystream" GROUP BY ts

Supported: =, !=, >, <, >=, <=, IS NULL, IS NOT NULL, AND, OR, NOT, COUNT, SUM, AVG, MIN, MAX, GROUP BY, ORDER BY, match_all(), histogram(). String literals use single quotes. Stream names use double quotes.

Optional: Langfuse Tracing

Set the following environment variables to emit traces to Langfuse:

| Variable | Description | |----------|-------------| | LANGFUSE_O2_ENABLED | Set to "true" to enable | | LANGFUSE_O2_PUBLIC_KEY | Langfuse project public key | | LANGFUSE_O2_SECRET_KEY | Langfuse project secret key | | LANGFUSE_O2_BASE_URL | Langfuse host (default: https://cloud.langfuse.com) |

Requirements

• Node.js ≥ 18.0.0
• OpenObserve instance with API access

License

MIT © Adarsh BA