How to add GreptimeDB MCP Server to Cursor

Query and analyze GreptimeDB observability data (metrics, logs, traces) via SQL, TQL, and RANGE queries. Paste the config into ~/.cursor/mcp.json and restart Cursor.

Last updated June 14, 2026 · 28★ · stdio · no auth

Cursor config for GreptimeDB MCP Server

pip install greptimedb-mcp-server

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

Setup steps

1Open Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
2Paste the GreptimeDB MCP Server config below into the "mcpServers" object.
3Fill in placeholder secrets, then save.
4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
5Ask Cursor to use one of GreptimeDB MCP Server's tools to confirm it's connected.

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)

What GreptimeDB MCP Server can do in Cursor

execute_sql

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

execute_tql

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

query_range

Execute time-window aggregation queries with RANGE/ALIGN syntax.

describe_table

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

explain_query

Analyze 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_check

Check database connection status and server version.

list_pipelines

List all pipelines or get details of a specific pipeline.

create_pipeline

Create a new pipeline with YAML configuration.

Security

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the GreptimeDB MCP Server config there under the "mcpServers" key and restart the client.

Is GreptimeDB MCP Server safe to use with Cursor?

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.

View repo Full GreptimeDB MCP Server page