GreptimeDB MCP Server
Query and analyze GreptimeDB observability data (metrics, logs, traces) via SQL, TQL, and RANGE queries.
Add to your client
Copy the config for your MCP client and paste it into its config file.
pip install greptimedb-mcp-serverPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"greptimedb-mcp-server": {
"command": "greptimedb-mcp-server",
"args": [
"--host",
"localhost",
"--database",
"public"
]
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python with pip (install via `pip install greptimedb-mcp-server`)
- A running GreptimeDB instance reachable via its MySQL protocol port (default 4002)
- Optionally a read-only GreptimeDB user (recommended) and HTTP API port 4000 for pipeline/dashboard management
- mcp>=1.8.0 required only for HTTP server mode (SSE / streamable-HTTP)
About GreptimeDB MCP Server
GreptimeDB MCP Server is the official MCP integration for GreptimeDB, an open-source observability database unifying metrics, logs, and traces. It exposes tools to run SQL, TQL (PromQL-compatible), and RANGE/ALIGN queries; inspect table profiles; explain query plans; check database health; and manage ingestion pipelines and Perses dashboards. A security gate enforces read-only access by default, masks sensitive columns, and audit-logs every tool call. Resources expose table data via greptime://<table>/data URIs, and built-in Jinja prompts assist with pipeline creation, metrics/PromQL/trace analysis, schema design, and query performance tuning. It connects over GreptimeDB's MySQL protocol port (4002) by default and can run over stdio, SSE, or streamable-HTTP.
Tools & capabilities (13)
execute_sqlExecute SQL queries with format (csv/json/markdown) and limit options.
execute_tqlExecute TQL (PromQL-compatible) queries for time-series analysis.
query_rangeExecute time-window aggregation queries with RANGE/ALIGN syntax.
describe_tableInspect a table profile: schema, semantic metadata, latest sample rows, and query guidance.
explain_queryAnalyze SQL or TQL query execution plans (analyze=true for runtime stats; verbose=true with analyze=true for per-partition scan metrics and index-pruning counters).
health_checkCheck database connection status and server version.
list_pipelinesList all pipelines or get details of a specific pipeline.
create_pipelineCreate a new pipeline with YAML configuration.
dryrun_pipelineTest a pipeline with sample data without writing to the database.
delete_pipelineDelete a specific version of a pipeline.
list_dashboardsList all Perses dashboard definitions.
create_dashboardCreate or update a Perses dashboard definition.
delete_dashboardDelete a dashboard definition.
What this server can do
GreptimeDB MCP Server provides tools for these capabilities — tap one to see every MCP server that does the same:
When to use it
- Let an AI assistant query metrics, logs, and traces in GreptimeDB using natural language translated to SQL or PromQL-compatible TQL
- Run time-window aggregations over time-series data with RANGE/ALIGN queries
- Inspect table schemas and explain query execution plans to debug and tune observability queries
- Create, dry-run, and manage ingestion pipelines and Perses dashboards from an AI workflow
- Provide safe, read-only analytical access to a production observability database with data masking and audit logging
Security notes
Read-only by default. 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 (hex, UNHEX, CHAR). Enabling GREPTIMEDB_ALLOW_WRITE=true (or --allow-write true) bypasses the gate for execute_sql and lets the AI run destructive DDL/DML — never enable against production data. Sensitive columns (password, secret, token, api_key, credential, credit_card, cvv, bank_account, ssn, id_card, passport) are automatically masked. A read-only GreptimeDB user is recommended; all tool invocations are audit-logged.
GreptimeDB MCP Server FAQ
Is the server read-only?
Yes, by default. A security gate blocks all destructive/DDL/DML statements. You can enable write mode with GREPTIMEDB_ALLOW_WRITE=true or --allow-write true, but this bypasses the gate for execute_sql and is intended only for local development or testing — never against production data.
How does it connect to GreptimeDB?
Over GreptimeDB's MySQL protocol port (default 4002). Configure host, port, user, password, database, and timezone via CLI flags or GREPTIMEDB_* environment variables. Pipeline and dashboard management additionally use the HTTP API port (default 4000).
Which transports are supported?
stdio by default. For containerized or Kubernetes deployments it also supports SSE and streamable-HTTP (set --transport, requires mcp>=1.8.0). DNS rebinding protection is disabled by default and can be enabled with --allowed-hosts.
How is sensitive data protected?
Columns whose names match patterns like password, secret, token, api_key, credential, credit_card, cvv, bank_account, ssn, id_card, and passport are automatically masked (******). You can add custom patterns with --mask-patterns. All tool invocations are also audit-logged.
Alternatives to GreptimeDB MCP Server
Compare all alternatives →
Google's official MCP server with prebuilt BigQuery tools, querying datasets via Application Default Credentials.
Create, manage, and query your InstantDB apps, schemas, permissions, and data from your AI editor.
Compare GreptimeDB MCP Server with: