Greptimedb MCP Server

What GreptimeTeam/greptimedb-mcp-server MCP server does

GreptimeTeam/greptimedb-mcp-server MCP server exposes GreptimeDB capabilities through the Model Context Protocol. It is intended for databases containing observability data such as metrics, logs, and traces. Agents can query data with SQL, TQL, or GreptimeDB range syntax, inspect table structure and semantic metadata, review query plans, and check database connectivity.

The server also covers selected operational workflows. Its tools can list, create, test, and delete pipelines, as well as list, create, update, and delete Perses dashboard definitions. A table-data resource uses greptime://<table>/data URIs, and built-in Jinja prompts support tasks including metrics analysis, PromQL analysis, trace analysis, schema design, ingestion troubleshooting, and query tuning.

How it works

After installation, the greptimedb-mcp-server executable connects to GreptimeDB using the configured host, port, database, user, and password. The default transport is stdio, which suits desktop MCP clients. HTTP deployments can use streamable HTTP or the legacy SSE mode, with configurable bind settings, CORS origins, and allowed hosts.

execute_sql accepts output formatting and row-limit options. execute_tql handles PromQL-compatible time-series queries, while query_range supports time-window aggregation with RANGE and ALIGN syntax. explain_query can return runtime analysis and, when verbose analysis is enabled, per-partition scan and index-pruning information. Semantic discovery reads information_schema.table_semantics; entity declarations require GreptimeDB 1.3 or later.

Setup and configuration

Install the Python package with:

pip install greptimedb-mcp-server

A basic local launch is:

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

Connection settings are available through CLI options or GREPTIMEDB_* environment variables. These include the database host, MySQL protocol port, credentials, database name, timezone, connection-pool size, HTTP API settings, transport, and HTTP listen settings. Pipeline and dashboard operations use the configured HTTP API port and protocol.

For Claude Desktop, configure the server command with arguments such as --host localhost and --database public. Container or Kubernetes deployments can select --transport streamable-http and a listen port. DNS rebinding protection is disabled by default, but allowed hosts and origins can be supplied when needed.

Tools and capabilities

GreptimeTeam/greptimedb-mcp-server MCP server provides these documented tool groups:

• Querying: execute_sql, execute_tql, query_range, and explain_query.
• Inspection: describe_table, search_table_semantics, and health_check.
• Pipelines: list_pipelines, create_pipeline, dryrun_pipeline, and delete_pipeline.
• Dashboards: list_dashboards, create_dashboard, and delete_dashboard.
• Resources: browse table data through greptime://<table>/data.
• Prompts: reusable templates for observability analysis, operations, and database design.

Limitations and notes

The server is read-only by default. Its application security gate blocks destructive or modifying SQL, including DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, and COPY, while allowing read and analysis statements such as SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, and UNION. Setting GREPTIMEDB_ALLOW_WRITE=true or the equivalent CLI option bypasses that gate for execute_sql and is intended only for local development or testing.

Sensitive values can be masked using built-in column-name patterns for credentials, financial data, and personal identifiers. Additional patterns are configurable. Tool invocations are audit-logged by default, and audit logging can be disabled. entity_declarations is unavailable on GreptimeDB versions before 1.3, where the field is reported as missing rather than empty.