greptimedb-mcp-server

Name: greptimedb-mcp-server
Author: GreptimeTeam

@GreptimeTeam

Repository

About greptimedb-mcp-server

A Model Context Protocol (MCP) server for GreptimeDB

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "greptimedb-mcp-server": {
      "command": "uv",
      "args": [
        "venv",
        "&&",
        "source",
        ".venv/bin/activate"
      ]
    }
  }
}

Tools

Execute SQL queries with format (csv/json/markdown) and limit options

Execute TQL (PromQL-compatible) queries for time-series analysis

Execute time-window aggregation queries with RANGE/ALIGN syntax

Inspect a table profile: schema, semantic metadata, latest sample rows, and query guidance

Analyze SQL or TQL query execution plans (`analyze=true` for runtime stats; add `verbose=true` alongside `analyze=true` for per-partition scan metrics and index-pruning counters)

Check database connection status and server version

Overview

What is greptimedb-mcp-server?

It is a Model Context Protocol (MCP) server for GreptimeDB, an open-source observability database that handles metrics, logs, and traces. It enables AI assistants to query and analyze GreptimeDB using SQL, TQL (PromQL-compatible), and RANGE queries, with built-in security features like read-only enforcement and data masking.

How to use greptimedb-mcp-server?

Install via pip install greptimedb-mcp-server, then run greptimedb-mcp-server --host localhost --database public. For Claude Desktop, add the MCP server configuration to your claude_desktop_config.json. The server can also be started in HTTP server mode for containerized deployments.

Key features of greptimedb-mcp-server

Execute SQL, TQL, and time-window aggregation queries.
Inspect table schemas and query execution plans.
List, create, test, and delete pipelines.
List, create, and delete Perses dashboards.
Read-only security gate blocking destructive SQL by default.
Automatic data masking for sensitive columns.
Audit logging of all tool invocations.

Use cases of greptimedb-mcp-server

Query and analyze observability metrics, logs, and traces with AI assistants.
Automate pipeline and dashboard management via MCP tools.
Debug and optimize queries by inspecting execution plans.
Enforce security policies (read-only, masking, audit) for AI-driven database access.

FAQ from greptimedb-mcp-server

Is the server read-only by default?

Yes. All queries pass through a security gate that blocks DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY, and encoded bypass attempts. Only SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, and UNION are allowed.

How can I enable write mode?

Set the environment variable GREPTIMEDB_ALLOW_WRITE=true or use the CLI argument --allow-write true. This bypasses the security gate for execute_sql and is intended only for local development or testing, never for production.

What transport modes are supported?

The server supports stdio (default), SSE (legacy), and streamable-http (recommended for production). Transport is set via the --transport CLI argument or GREPTIMEDB_TRANSPORT environment variable.

What are the runtime requirements?

A running GreptimeDB instance accessible via MySQL protocol (default port 4002) and optionally via HTTP (port 4000) for pipeline and dashboard management. Python with the installed package is required.

Can I use data masking with custom patterns?

Yes. Data masking is enabled by default for known sensitive column names. You can add custom patterns via --mask-patterns phone,email or the GREPTIMEDB_MASK_PATTERNS environment variable.