greptimedb-mcp-server — Claude Code MCP server: how to install
Connects AI assistants to GreptimeDB to inspect logs, traces, and metrics with SQL or TQL. Helpful for running observability queries, pipelines, and dashboards.
claude mcp add --env GREPTIMEDB_HOST=<GREPTIMEDB_HOST> --env GREPTIMEDB_PORT=<GREPTIMEDB_PORT> --env GREPTIMEDB_USER=<GREPTIMEDB_USER> --env GREPTIMEDB_PASSWORD=<GREPTIMEDB_PASSWORD> --env GREPTIMEDB_DATABASE=<GREPTIMEDB_DATABASE> --transport stdio greptimedb-mcp-server -- uvx greptimedb-mcp-serverWhat greptimedb-mcp-server 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.
What it helps with
- 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 for the agent
- 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
How to install greptimedb-mcp-server
Platform CLI
claude mcp add --env GREPTIMEDB_HOST=<GREPTIMEDB_HOST> --env GREPTIMEDB_PORT=<GREPTIMEDB_PORT> --env GREPTIMEDB_USER=<GREPTIMEDB_USER> --env GREPTIMEDB_PASSWORD=<GREPTIMEDB_PASSWORD> --env GREPTIMEDB_DATABASE=<GREPTIMEDB_DATABASE> --transport stdio greptimedb-mcp-server -- uvx greptimedb-mcp-serverReplace <…> 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 <command>
Platform CLI
codex mcp add greptimedb-mcp-server --env GREPTIMEDB_HOST=<GREPTIMEDB_HOST> --env GREPTIMEDB_PORT=<GREPTIMEDB_PORT> --env GREPTIMEDB_USER=<GREPTIMEDB_USER> --env GREPTIMEDB_PASSWORD=<GREPTIMEDB_PASSWORD> --env GREPTIMEDB_DATABASE=<GREPTIMEDB_DATABASE> -- uvx greptimedb-mcp-serverReplace <…> 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 <command>
Config file
{
"mcpServers": {
"greptimedb-mcp-server": {
"command": "uvx",
"args": [
"greptimedb-mcp-server"
],
"env": {
"GREPTIMEDB_HOST": "<GREPTIMEDB_HOST>",
"GREPTIMEDB_PORT": "<GREPTIMEDB_PORT>",
"GREPTIMEDB_USER": "<GREPTIMEDB_USER>",
"GREPTIMEDB_PASSWORD": "<GREPTIMEDB_PASSWORD>",
"GREPTIMEDB_DATABASE": "<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 <command>
Config file
{
"servers": {
"greptimedb-mcp-server": {
"type": "stdio",
"command": "uvx",
"args": [
"greptimedb-mcp-server"
],
"env": {
"GREPTIMEDB_HOST": "<GREPTIMEDB_HOST>",
"GREPTIMEDB_PORT": "<GREPTIMEDB_PORT>",
"GREPTIMEDB_USER": "<GREPTIMEDB_USER>",
"GREPTIMEDB_PASSWORD": "<GREPTIMEDB_PASSWORD>",
"GREPTIMEDB_DATABASE": "<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 <command>
Platform CLI
gemini mcp add -e GREPTIMEDB_HOST=<GREPTIMEDB_HOST> -e GREPTIMEDB_PORT=<GREPTIMEDB_PORT> -e GREPTIMEDB_USER=<GREPTIMEDB_USER> -e GREPTIMEDB_PASSWORD=<GREPTIMEDB_PASSWORD> -e GREPTIMEDB_DATABASE=<GREPTIMEDB_DATABASE> greptimedb-mcp-server uvx greptimedb-mcp-serverReplace <…> 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 <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about greptimedb-mcp-server
How do I install greptimedb-mcp-server in Claude Code?
Run claude mcp add greptimedb-mcp-server -e GREPTIMEDB_PASSWORD=<GREPTIMEDB_PASSWORD> -- uvx greptimedb-mcp-server in your terminal.
What does greptimedb-mcp-server do?
It allows models to run analytical queries, inspect table structures, manage ingestion pipelines, and review dashboards in GreptimeDB.
Why are semantic graph tools not showing up?
The query_semantic_graph tool requires GreptimeDB 1.3 and access to greptime_private views. If these views are missing or unreadable, the server disables the tool during startup.
