Skip to content

README.md

Latest commit

 

History

History
138 lines (106 loc) · 4.27 KB

README.md

File metadata and controls

138 lines (106 loc) · 4.27 KB
Raw

OpenObserve MCP Server

npm version License: MIT TypeScript

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 "user@example.com: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