Skip to main content
Glama
OpenObserve MCP Server

OpenObserve MCP Server

by bilscode
README.md
# OpenObserve MCP Server

Read-only [MCP](https://modelcontextprotocol.io) server for the OpenObserve Open Source edition. It lets an MCP client discover and investigate logs and metrics, and exposes no tool that modifies data or configuration.

## Tools

- `health_check`: verifies connectivity, credentials, and configured organization scope.
- `list_organizations`: lists only organizations allowed by local configuration.
- `list_streams`: compact stream list with filtering, sorting, pagination, and data-only filtering.
- `get_stream_overview`: stream stats and field list.
- `get_stream_schema`: full schema, stats, and settings for a selected stream.
- `search_logs`: read-only SQL search with time-range, result-size, and SQL-statement guardrails.
- `search_values`: frequent distinct field values in a selected time range.
- `search_around`: records around a `_timestamp`, within OpenObserve's five-minute context window.
- `query_metrics` and `query_metrics_range`: read-only PromQL queries.

## Guardrails

- Only organizations listed in `O2_ALLOWED_ORGS` can be queried.
- Requests time out after `O2_REQUEST_TIMEOUT_MS` (30 seconds by default).
- SQL accepts one `SELECT` or `WITH` statement. Semicolons and write or administrative keywords are rejected.
- Search results are capped at 100 records. Field-value and around searches have separate caps.
- A log-search range over seven days requires `allow_large_range: true`.
- Tool output is capped at 50,000 characters.

### Limitations

- These are MCP-side safety limits, not a security boundary. **The permissions of the OpenObserve user you authenticate with are the real authorization boundary.** Use a dedicated read-only account, not a personal or admin account.
- The SQL check is a keyword filter. It can reject harmless queries, for example a `LIKE '%update%'` filter or a string literal containing `;`.
- Authentication uses HTTP Basic Auth. Use an `https://` base URL, otherwise the credentials are sent unencrypted.

## Setup

Requirements: Node.js 18 or newer.

```bash
git clone https://github.com/bilscode/openobserve-mcp.git
cd openobserve-mcp
npm install
npm run build
```

Configure through environment variables, either exported in your shell or set in your MCP client:

```bash
export O2_BASE_URL="https://openobserve.example.com"
export O2_AUTH_TOKEN="<base64-of-email:password>"
export O2_ALLOWED_ORGS="my-org-dev,my-org-prod"
export O2_REQUEST_TIMEOUT_MS="30000"
```

| Variable | Required | Description |
|---|---|---|
| `O2_BASE_URL` | yes | OpenObserve base URL |
| `O2_AUTH_TOKEN` | yes | Base64 of `email:password` for Basic Auth |
| `O2_ALLOWED_ORGS` | yes | Comma-separated organization identifiers the server may query |
| `O2_REQUEST_TIMEOUT_MS` | no | Request timeout in milliseconds, default `30000` |

Generate the Basic Auth token locally:

```bash
printf '%s' 'email@example.com:password' | base64
```

Never commit the token or a real password. Base64 is encoding, not encryption. Rotate any credential that has been shared in chat, committed, or placed in documentation.

## MCP Client Configuration

Example command-based configuration:

```json
{
  "mcpServers": {
    "openobserve": {
      "command": "node",
      "args": ["/absolute/path/to/openobserve-mcp/dist/index.js"],
      "env": {
        "O2_BASE_URL": "https://openobserve.example.com",
        "O2_AUTH_TOKEN": "<base64-of-email:password>",
        "O2_ALLOWED_ORGS": "my-org-dev,my-org-prod",
        "O2_REQUEST_TIMEOUT_MS": "30000"
      }
    }
  }
}
```

## Example prompts

```text
Run health_check.
List streams with data in my-org-dev, sorted by storage.
Show the overview for my_app_logs in my-org-dev.
Find the twenty most common values of the "service" field in the last hour.
Search the last hour for errors in a selected stream, returning at most 20 rows.
Show logs around timestamp 1793332367611355 in a selected stream.
```

OpenObserve's API uses epoch microseconds for log search timestamps:

```js
const endTime = Date.now() * 1000;
const startTime = (Date.now() - 60 * 60 * 1000) * 1000;
```

## Development

```bash
npm run build
npm start
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

## License

[MIT](LICENSE)

## References

- https://openobserve.ai/docs/reference/api/
- https://openobserve.ai/docs/reference/api/search/search/
- https://openobserve.ai/docs/reference/api/search/value/
- https://openobserve.ai/docs/reference/api/search/around/