# greptimedb-mcp-server Connects AI assistants to GreptimeDB to inspect logs, traces, and metrics with SQL or TQL. Helpful for running observability queries, pipelines, and dashboards. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 29 - Author: GreptimeTeam - License: MIT · policy=link-only · description only; the file stays with the author - Source: https://github.com/GreptimeTeam/greptimedb-mcp-server - Updated: 2026-10-12 - HTML: https://affpapa.org/en/nevibecode/mcp/greptimedb-mcp-server ## What it does This MCP server connects your coding assistant to GreptimeDB. It exposes tools to run analytical queries in SQL or PromQL-compatible TQL, inspect table structures via `describe_table`, and check execution plans with `explain_query`. Safety guardrails are strict out of the box. Write access stays blocked by default via `GREPTIMEDB_ALLOW_WRITE=false`, preventing unintended schema alterations or record edits. Result payloads are capped by `GREPTIMEDB_MAX_RESULT_BYTES` (1048576 bytes by default), so oversized responses get trimmed cleanly. Advanced features require a modern database engine. The semantic graph tools and entity declarations depend on GreptimeDB 1.3. If the required views are missing or lack read permissions, the server omits those tools during startup. ## Requirements - Needs: Python and uv (commands run via uvx) - Environment variables: `GREPTIMEDB_HOST`, `GREPTIMEDB_PORT`, `GREPTIMEDB_USER`, `GREPTIMEDB_PASSWORD`, `GREPTIMEDB_DATABASE`, `GREPTIMEDB_TIMEZONE`, `GREPTIMEDB_POOL_SIZE`, `GREPTIMEDB_HTTP_PORT`, `GREPTIMEDB_HTTP_PROTOCOL`, `GREPTIMEDB_MASK_ENABLED` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env GREPTIMEDB_HOST= --env GREPTIMEDB_PORT= --env GREPTIMEDB_USER= --env GREPTIMEDB_PASSWORD= --env GREPTIMEDB_DATABASE= --transport stdio greptimedb-mcp-server -- uvx greptimedb-mcp-server ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from greptimedb-mcp-server ### Codex **Platform CLI** ```bash codex mcp add greptimedb-mcp-server --env GREPTIMEDB_HOST= --env GREPTIMEDB_PORT= --env GREPTIMEDB_USER= --env GREPTIMEDB_PASSWORD= --env GREPTIMEDB_DATABASE= -- uvx greptimedb-mcp-server ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from greptimedb-mcp-server ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "greptimedb-mcp-server": { "command": "uvx", "args": [ "greptimedb-mcp-server" ], "env": { "GREPTIMEDB_HOST": "", "GREPTIMEDB_PORT": "", "GREPTIMEDB_USER": "", "GREPTIMEDB_PASSWORD": "", "GREPTIMEDB_DATABASE": "" } } } } ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from greptimedb-mcp-server ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "greptimedb-mcp-server": { "type": "stdio", "command": "uvx", "args": [ "greptimedb-mcp-server" ], "env": { "GREPTIMEDB_HOST": "", "GREPTIMEDB_PORT": "", "GREPTIMEDB_USER": "", "GREPTIMEDB_PASSWORD": "", "GREPTIMEDB_DATABASE": "" } } } } ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from greptimedb-mcp-server ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e GREPTIMEDB_HOST= -e GREPTIMEDB_PORT= -e GREPTIMEDB_USER= -e GREPTIMEDB_PASSWORD= -e GREPTIMEDB_DATABASE= greptimedb-mcp-server uvx greptimedb-mcp-server ``` Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from greptimedb-mcp-server ## When to use it - run SQL and PromQL-compatible TQL queries over metrics or logs - inspect query execution plans with runtime stats and index counters - test data pipeline configurations with sample input before saving - manage Perses dashboard definitions through automated tools ## Example prompts - Run an explain_query with analyze enabled for the slow latency metric query - Search table semantics for http request error counts across the public schema - Run a dryrun_pipeline test on the new access log parser with sample text ## Similar - [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408 - [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433 - [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717 - [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409 - [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669 - [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md