GreptimeDB MCP Server for Metrics, Logs, Traces

Overview

GreptimeDB MCP Server exposes GreptimeDB as a Model Context Protocol (MCP) server so AI assistants and tools can query metrics, logs, and traces using a consistent, secure interface. It translates MCP tool calls into SQL, TQL (PromQL-compatible), and time-range queries, returning structured results in CSV/JSON/Markdown formats. The server is intended for environments where you want programmatic access to observability data without giving an LLM or external agent full write privileges.

It is useful for debugging, analytics, automated report generation, and integration with assistant clients (e.g., Claude Desktop). The server supports read-only enforcement, data masking, audit logging, and multiple transport modes (stdio, SSE, streamable HTTP) to suit local, desktop, and containerized deployments.

Features

• Read-only query execution with blocking of harmful DDL/DML operations
• Support for SQL, TQL (PromQL-compatible), and RANGE/ALIGN time-window queries
• Results returned in CSV, JSON, or Markdown table formats
• Built-in data masking and audit logging options
• Pipeline and dashboard management (create, list, dry-run, delete)
• HTTP server mode with streamable HTTP or SSE transports for container/Kubernetes deployments
• Prompts and resource URIs for LLM-driven workflows (e.g., pipeline_creator, metrics_analysis)

Available Tools

Key tools exposed to MCP clients:

Tool	Purpose
execute_sql	Run ad-hoc SQL queries; supports format and row limits
execute_tql	Run PromQL-compatible TQL queries for time-series analysis
query_range	Run RANGE/ALIGN windowed aggregation queries across a time range
describe_table	Return schema (columns, types, constraints) for a table
explain_query	Return execution plan information for SQL/TQL
health_check	Verify DB connection and server version
list_pipelines / create_pipeline / dryrun_pipeline / delete_pipeline	Manage ingestion pipelines (YAML) and test them without persisting
list_dashboards / create_dashboard / delete_dashboard	Manage Perses dashboard JSON/YAML definitions

Resources: tables can be referenced as greptime://

/data to let assistants discover available datasets.

Installation / Configuration

Install from PyPI:

pip install greptimedb-mcp-server

Quick run (defaults to GreptimeDB on localhost:4002):

greptimedb-mcp-server --host localhost --database public

Example Claude Desktop config (macOS):

{
  "mcpServers": {
    "greptime": {
      "command": "greptimedb-mcp-server",
      "args": ["--host", "localhost", "--database", "public"]
    }
  }
}

Important environment variables:

export GREPTIMEDB_HOST=localhost
export GREPTIMEDB_PORT=4002
export GREPTIMEDB_USER=root
export GREPTIMEDB_PASSWORD=""
export GREPTIMEDB_DATABASE=public
export GREPTIMEDB_TIMEZONE=UTC

# Optional
export GREPTIMEDB_HTTP_PORT=4000
export GREPTIMEDB_POOL_SIZE=5
export GREPTIMEDB_MASK_ENABLED=true
export GREPTIMEDB_AUDIT_ENABLED=true
export GREPTIMEDB_TRANSPORT=stdio

CLI options mirror common environment variables:

greptimedb-mcp-server \
  --host localhost \
  --port 4002 \
  --database public \
  --user root \
  --password "" \
  --timezone UTC \
  --pool-size 5 \
  --mask-enabled true \
  --transport stdio

HTTP Server Mode (container / k8s)

Streamable HTTP (recommended):

greptimedb-mcp-server --transport streamable-http --listen-port 8080

SSE (legacy):

greptimedb-mcp-server --transport sse --listen-port 3000

DNS rebinding protection: by default it is disabled for compatibility. Enable with --allowed-hosts and set CORS via --allowed-origins:

greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "localhost:*,my-service.namespace:*" \
  --allowed-origins "http://localhost:*"

If you encounter “421 Invalid Host Header”, add the host to allowed hosts or disable protection (default).

Security

Recommended: create a read-only database user and use the server in read-only mode. The server enforces an application-level security gate that blocks destructive statements, including but not limited to:

• DROP, DELETE, TRUNCATE, UPDATE, INSERT
• ALTER, CREATE, GRANT, REVOKE
• EXEC, LOAD, COPY

Optional safeguards:

• Data masking (regex patterns) to hide sensitive fields
• Audit logging to track queries and responses
• Connection pool and session timezone settings

Use Cases

• Ad-hoc metrics investigation: use execute_tql to run PromQL-style queries and return results as JSON for an LLM to analyze trends.
• Log ingestion pipeline development: create and dry-run a YAML pipeline to validate parsing and transformation before writing to GreptimeDB.
• Time-window analysis: run query_range with ALIGN to compute rolling aggregations (e.g., per-minute averages across a 24-hour window).
• Dashboard automation: programmatically create/update Perses dashboard definitions after analysis or alerts are generated.
• Desktop assistant integration: wire greptimedb-mcp-server into Claude Desktop to enable conversational querying over observability data without exposing write permissions.

For full examples, prompts, and LLM instructions, see the project repository: https://github.com/GreptimeTeam/greptimedb-mcp-server.