How to add GreptimeDB MCP Server to Windsurf

Query and analyze GreptimeDB observability data (metrics, logs, traces) via SQL, TQL, and RANGE queries. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the GreptimeDB MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5GreptimeDB MCP Server's tools become available to Cascade.

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 Windsurf

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

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the GreptimeDB MCP Server config there under the "mcpServers" key and restart the client.

Is GreptimeDB MCP Server safe to use with Windsurf?

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