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/
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data