Version: 1.3

Model Context Protocol (MCP)

Experimental Feature

The GreptimeDB MCP Server is currently in experimental stage and under active development. APIs and features may change without notice. Please use with caution in production environments.

The GreptimeDB MCP Server provides a Model Context Protocol implementation that enables AI assistants like Claude to securely query and analyze your GreptimeDB databases using SQL, TQL (PromQL-compatible), and RANGE queries — with a read-only SQL gate and data masking built in.

Watch our demo video on YouTube to see the MCP Server in action.

What is MCP?

Model Context Protocol (MCP) is a standard protocol that lets AI assistants interact with external data sources and tools. With the GreptimeDB MCP Server, an assistant can explore your tables, understand what each one represents through the semantic layer, run queries, and manage pipelines and dashboards.

Tools

The following tools are available in server v0.6.1.

Query and inspection

Tool	Description
`execute_sql`	Execute a SQL query (MySQL dialect). `format` is `csv` (default), `json`, or `markdown`; `limit` defaults to `1000` rows and is clamped to `1`–`10000`.
`execute_tql`	Execute a TQL (PromQL-compatible) query with `query`, `start`, `end`, `step`, and an optional `lookback` (default `5m`). Returns at most 10000 rows.
`query_range`	Execute a time-window aggregation query with RANGE/ALIGN syntax. `table`, `select`, and `align` are required; `by`, `where`, `fill`, and `order_by` are optional.
`search_table_semantics`	Find tables by observability concept, such as `redis memory usage`. Searches table names, semantic options, and entity declarations in one database, and ranks tables by matched terms. Optional `signal_type`, `schema`, and `limit` (default and maximum `50`).
`query_semantic_graph`	Query the semantic graph. `view` is `summary`, `entities`, or `relationships`; `start_time` and `end_time` (RFC 3339) define a required half-open window. Entity and relationship filters are optional; `limit` defaults to `100` (maximum `500`).
`describe_table`	Inspect a table profile: schema, semantic metadata, sample rows (default `5`, maximum `20`), and query guidance.
`explain_query`	Show the execution plan of a SQL query or a `TQL EVAL` statement. `analyze=true` executes the query and reports runtime metrics; `verbose=true` adds per-partition scan metrics.
`health_check`	Check database connection status and server version.

execute_sql, query_range, and describe_table accept schema.table to read another database. execute_tql reads another database with the __schema__ matcher, for example metric{__schema__="other_db"}. The connected user needs read permission on that database.

describe_table and search_table_semantics read the table semantics, so the assistant learns the signal type, source, and metric metadata of a table instead of guessing from column names. search_table_semantics returns only tables that carry greptime.semantic.* options or receive entity declarations from a built-in convention. Entity declarations require GreptimeDB v1.3 or later. query_semantic_graph reads greptime_private.semantic_entities and greptime_private.semantic_relationships, which also require v1.3 or later. If these views are missing or not readable by the connected user at startup, the server does not offer query_semantic_graph.

Tool results are limited to GREPTIMEDB_MAX_RESULT_BYTES (1 MiB by default). A larger query result returns fewer rows and reports the truncation.

Pipeline management

Tool	Description
`list_pipelines`	List all pipelines or get details of a specific pipeline.
`create_pipeline`	Create a new pipeline version with YAML configuration. Requires write mode.
`dryrun_pipeline`	Test an inline or saved pipeline with sample data without writing to the database.
`delete_pipeline`	Delete a specific version of a pipeline. Requires write mode.

Dashboard management

Tool	Description
`list_dashboards`	List all Perses dashboard definitions.
`create_dashboard`	Create or overwrite a Perses dashboard definition. Requires write mode.
`delete_dashboard`	Delete a dashboard definition. Requires write mode.

Resources and prompts

Tables can be read as resources through greptime://<table>/data URIs, which return up to 100 rows.

The server also ships built-in Jinja prompt templates: pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, and query_performance_tuning.

Installation

The server requires Python 3.11 or later.

pip install greptimedb-mcp-server

Run it directly (connects to localhost:4002 by default):

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

Configuration

The server is configured through environment variables or CLI arguments.

Environment variable	CLI argument	Default	Description
`GREPTIMEDB_HOST`	`--host`	`localhost`	Database host.
`GREPTIMEDB_PORT`	`--port`	`4002`	MySQL protocol port.
`GREPTIMEDB_USER`	`--user`	Empty	Database user.
`GREPTIMEDB_PASSWORD`	`--password`	Empty	Database password.
`GREPTIMEDB_DATABASE`	`--database`	`public`	Database name.
`GREPTIMEDB_TIMEZONE`	`--timezone`	Empty	Session timezone.
`GREPTIMEDB_POOL_SIZE`	`--pool-size`	`5`	Connection pool size.
`GREPTIMEDB_HTTP_PORT`	`--http-port`	`4000`	HTTP API port, used by the pipeline and dashboard tools.
`GREPTIMEDB_HTTP_PROTOCOL`	`--http-protocol`	`http`	HTTP API protocol: `http` or `https`.
`GREPTIMEDB_MASK_ENABLED`	`--mask-enabled`	`true`	Mask sensitive columns.
`GREPTIMEDB_MASK_PATTERNS`	`--mask-patterns`	Empty	Additional sensitive column name patterns, comma-separated.
`GREPTIMEDB_AUDIT_ENABLED`	`--audit-enabled`	`true`	Log every tool invocation.
`GREPTIMEDB_ALLOW_WRITE`	`--allow-write`	`false`	Allow DDL/DML through `execute_sql` and the pipeline and dashboard write tools. See Write mode.
`GREPTIMEDB_MAX_RESULT_BYTES`	`--max-result-bytes`	`1048576`	Byte budget for a single tool result.
`GREPTIMEDB_TRANSPORT`	`--transport`	`stdio`	Transport: `stdio`, `sse`, or `streamable-http`.
`GREPTIMEDB_LISTEN_HOST`	`--listen-host`	`0.0.0.0`	Bind host for the `sse` and `streamable-http` transports.
`GREPTIMEDB_LISTEN_PORT`	`--listen-port`	`8080`	Bind port for the `sse` and `streamable-http` transports.
`GREPTIMEDB_ALLOWED_HOSTS`	`--allowed-hosts`	Empty	Allowed hosts for DNS rebinding protection, comma-separated. Empty disables the protection.
`GREPTIMEDB_ALLOWED_ORIGINS`	`--allowed-origins`	Empty	Allowed CORS origins, comma-separated. Used only when `--allowed-hosts` is set.

Boolean options accept true/false, 1/0, yes/no, or on/off.

Claude Desktop integration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "greptimedb": {
      "command": "greptimedb-mcp-server",
      "args": ["--host", "localhost", "--database", "public"],
      "env": {
        "GREPTIMEDB_PORT": "4002",
        "GREPTIMEDB_USER": "your_username",
        "GREPTIMEDB_PASSWORD": "your_password"
      }
    }
  }
}

HTTP server mode

For containerized or Kubernetes deployments, run the server over HTTP instead of stdio:

# Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080

# SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000

DNS rebinding protection is disabled by default for compatibility with proxies and Kubernetes services. Enable it with --allowed-hosts, for example --allowed-hosts "localhost:*,127.0.0.1:*,my-service.namespace:*".

Security

The server is read-only by default. Without write mode, execute_sql rejects statements that the security gate blocks, and create_pipeline, delete_pipeline, create_dashboard, and delete_dashboard return an error without contacting GreptimeDB. list_pipelines, dryrun_pipeline, and list_dashboards remain available.

Security gate: blocks DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, REPLACE INTO, EXEC/EXECUTE, CALL, LOAD, COPY, OUTFILE, LOAD_FILE, INTO DUMPFILE, and encoded content such as UNHEX, hexadecimal literals, and CHAR().
Data masking: columns whose names contain patterns such as password, token, api_key, ssn, or credit_card are masked as ******. Add patterns with --mask-patterns.
Audit logging: every tool invocation is logged. Disable with --audit-enabled false.

For the strongest setup, also create a read-only database user with the static user provider and connect the server with it.

Write mode

For local development or testing, you can enable write mode:

greptimedb-mcp-server --allow-write true

Write mode allows DDL/DML statements (CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) through execute_sql by bypassing the security gate, and enables create_pipeline, delete_pipeline, create_dashboard, and delete_dashboard. The server logs a warning on startup.

danger

Write mode lets an AI assistant run destructive statements against your database. Never enable it against production data.

Learn More

For advanced usage and troubleshooting, refer to the GreptimeDB MCP Server documentation.

note

The GreptimeDB MCP Server is an experimental project still under development. Exercise caution when using it with sensitive data.

Model Context Protocol (MCP)

What is MCP?​

Tools​

Query and inspection​

Pipeline management​

Dashboard management​

Resources and prompts​

Installation​

Configuration​

Claude Desktop integration​

HTTP server mode​

Security​

Write mode​

Learn More​