GreptimeDB

by GreptimeTeam

Community Database 7k likes

An MCP server that lets an agent query GreptimeDB with SQL, PromQL-style TQL, and time-range aggregations, plus manage ingest pipelines and Perses dashboards, with read-only enforcement built in.

Install via pip

pip install greptimedb-mcp-server && greptimedb-mcp-server --host localhost --database public

Source: https://github.com/GreptimeTeam/greptimedb-mcp-server

About

This server gives an agent a controlled path into GreptimeDB, the metrics/logs/traces database, rather than raw database credentials. It can run arbitrary SQL, TQL (GreptimeDB's PromQL-compatible query language) for time-series analysis, and RANGE-syntax windowed aggregations, and it can describe a table's schema and sample rows or explain a query's execution plan before you run it, useful for an agent that's exploring an unfamiliar observability dataset rather than working from a known schema.

It goes past pure querying into operational tasks: listing, creating, dry-running, and deleting data ingest pipelines defined in YAML, and listing, creating, or deleting Perses dashboard definitions. The project is explicit about its current maturity. It enforces read-only query execution and includes data-masking options, but the README flags it as an experimental, still-developing tool and asks users to be cautious with data security in production settings.

Key features

  • SQL and TQL (PromQL-compatible) query execution against GreptimeDB
  • RANGE/ALIGN windowed time-series aggregation queries
  • Schema inspection and query-plan explanation before running a query
  • Ingest pipeline management: list, create, dry-run, and delete YAML pipelines
  • Perses dashboard management: list, create, and delete dashboard definitions
  • Read-only enforcement and data-masking options for safer agent access

Use cases

  • Letting an agent investigate a metrics/logs incident by querying GreptimeDB directly instead of relaying queries through a human
  • Building or dry-running new ingest pipelines from natural-language descriptions before deploying them
  • Auto-generating or adjusting Perses dashboards based on what an agent finds while exploring the data
  • Explaining slow queries by having the agent pull an execution plan and suggest schema or query fixes

Available tools

execute_sql

Runs a SQL query against GreptimeDB with configurable output format and row limit.

execute_tql

Runs a TQL (PromQL-compatible) query for time-series analysis.

query_range

Runs a time-windowed aggregation query using RANGE/ALIGN syntax.

describe_table

Returns a table's schema, metadata, and sample rows.

explain_query

Returns the execution plan for a given query.

create_pipeline

Creates a new ingest pipeline from a YAML definition.

Frequently asked questions

Can the agent write or delete data through this server?

Query execution is read-only by enforcement; the write-capable tools are limited to pipeline and dashboard configuration, not row-level data mutation.

What query languages does it support?

Standard SQL, GreptimeDB's PromQL-compatible TQL for time-series analysis, and RANGE/ALIGN syntax for windowed aggregations.