greptimedb-mcp-server
A Model Context Protocol (MCP) server for GreptimeDB — an open-source observability database that handles metrics, logs, and traces in one engine.
Enables AI assistants to query and analyze GreptimeDB using SQL, TQL (PromQL-compatible), and RANGE queries, with built-in security features like read-only enforcement and data masking.
Quick Start
# Install
pip install greptimedb-mcp-server
# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database publicFor Claude Desktop, add this to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"greptimedb": {
"command": "greptimedb-mcp-server",
"args": ["--host", "localhost", "--database", "public"]
}
}
}Features
Tools
| Tool | Description |
|---|---|
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 |
search_table_semantics |
Find tables by observability concept, ranked by matched terms; searches table names, semantic options, and entity declarations. schema selects the database to search |
query_semantic_graph |
Query the semantic graph: summary (what it contains), entities (nodes), relationships (edges) over a required time window |
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; add verbose=true alongside analyze=true for per-partition scan metrics and index-pruning counters) |
health_check |
Check database connection status and server version |
