Best for
- Developers working with time-series and observability data.
- Teams needing natural language access to their database for query and analysis.
- Users wanting to integrate AI-assisted data exploration within MCP clients.
G
GreptimeDB MCP Server
Official
Query and analyze GreptimeDB metrics, logs, and traces via SQL, TQL, and RANGE queries.
GitHub source repository ↗
60FMRS · C
GreptimeDB MCP Server provides a comprehensive set of tools for querying GreptimeDB with strong security features like read-only enforcement and data masking. Actively maintained and backed by the upstream team. Suitable for AI-driven observability workflows interacting with GreptimeDB.
GreptimeDB MCP Server is a Model Context Protocol (MCP) server that enables AI assistants to query and analyze GreptimeDB metrics, logs, and traces using SQL, TQL (PromQL-compatible), and RANGE queries. Includes built-in security features like read-only enforcement and data masking, as well as pipeline and Perses dashboard management.
Tools
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 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 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.
dryrun_pipeline
Test a pipeline with sample data without writing to database.
delete_pipeline
Delete a specific version of a pipeline.
list_dashboards
List all Perses dashboard definitions.
create_dashboard
Create or update a Perses dashboard definition.
delete_dashboard
Delete a dashboard definition.
Setup
- Install:
pip install greptimedb-mcp-server. 2. Run (connects to localhost:4002 by default):greptimedb-mcp-server --host localhost --database public. 3. For Claude Desktop, add the JSON config to~/Library/Application Support/Claude/claude_desktop_config.json.
claude_desktop_config.json
{
"mcpServers": {
"greptimedb": {
"command": "greptimedb-mcp-server",
"args": [
"--host",
"localhost",
"--database",
"public"
]
}
}
}
Fit and risk
Not for
- Users who need write operations or DDL/DML (read-only by default; write mode only for local/test, extremely risky).
- Users not using GreptimeDB.
- Users who need direct database access without MCP integration.
Required permissions
- Read-only access to GreptimeDB for SQL, TQL, and RANGE queries.
- Access to HTTP API (default port 4000) for pipeline and dashboard management.
- Access to configured credentials via environment variables or CLI arguments.
- Data masking is enabled by default to prevent sensitive column exposure.
Risks and side effects
- If write mode is enabled (disabled by default), AI could execute destructive SQL; never enable against production.
- Queries may be expensive if complex or misused; restrict access and resources.
- Providing secret environment variables over HTTP could increase exposure risk.
- Database may be inaccessible due to network configuration or startup issues.
Troubleshooting
- Check that GreptimeDB is running on the specified host and port.
- Verify connection parameters (host, port, database, user, password).
- Check server logs for audit records and queries blocked by the security gate.
- For HTTP mode, if you receive 421 Invalid Host Header errors, add allowed hosts or disable DNS rebinding protection.
Use cases
AI assistants querying and analyzing metrics, logs, and traces in GreptimeDB.
Executing SQL and PromQL queries via natural language for observability data.
Managing pipelines and Perses dashboards without writing config directly.
Supported clients
Claude DesktopFull support