GreptimeDB MCP Server

Official

Query and analyze GreptimeDB metrics, logs, and traces via SQL, TQL, and RANGE queries.

How to install ↓ Compare GitHub source repository ↗

Category: Database #17 of 58
Stars: ★ 29 Popular
Transport: stdio (local process)
Runtime: Python
Credentials: Optional API key
License: MIT
Last commit: 12 days ago
Tools: 13

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.

Strongest · Documentation 14/20 Weakest · Reliability 10/20

Reliability

10/20

Security and permissions

12/20

Maintenance

11/20

Documentation

14/20

Setup experience

13/20

Why each score

Reliability 10/20: README describes a coherent toolset, a security gate, audit logging, and claims CI plus pytest, but no test files or workflow contents were supplied for static verification that declared tools match behavior; static calibration caps this below 12, scored 10.
Security and permissions 12/20: Strong defaults: read-only by default, blocklist security gate with encoded-bypass detection, data masking, audit logging, isSecret marking on password fields, optional DNS rebinding protection. Deductions: GREPTIMEDB_ALLOW_WRITE fully bypasses the gate with no confirmation flow; password can be passed via CLI argument (process-list exposure); DNS rebinding protection disabled by default in HTTP mode. No red-line items, so above 4.
Maintenance 11/20: MIT license, version 0.6.0 aligned between manifest and PyPI, backed by the GreptimeTeam org, suggesting real ownership; but only 29 stars and 5 open issues, and no evidence of commit cadence, release cadence, or a security-response channel, scored 11.
Documentation 14/20: Well-layered docs: install, CLI/env reference, Claude Desktop config, security guidance (read-only user), troubleshooting (421 errors), and linked LLM integration docs. Deductions: no disclosure of cost/performance limits, masking bypass boundaries, or HTTP-mode security trade-offs; README/manifest are untrusted evidence without corroboration.
Setup experience 13/20: Simple path (pip install, one command, or a Claude Desktop JSON snippet), complete env/CLI reference, stdio default. HTTP/SSE modes add configuration complexity and require understanding security defaults; static evidence caps this at 15, scored 13.

Static review · not runListed 2026-09-08

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkConnects to a database

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.

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.

Setup

Before you start

Runtime：Python

GREPTIMEDB_PASSWORD optionalsecret Database password from your GreptimeDB instance configuration.

Other optional settings (17)

GREPTIMEDB_HOST optional GreptimeDB host address, defaults to localhost; no signup needed.

GREPTIMEDB_PORT optional MySQL protocol port, defaults to 4002.

GREPTIMEDB_USER optional Database username, optional.

GREPTIMEDB_DATABASE optional Database name to connect to, defaults to public.

GREPTIMEDB_TIMEZONE optional Session timezone, defaults to UTC.

GREPTIMEDB_HTTP_PORT optional HTTP API port for pipeline/dashboard management, defaults to 4000.

GREPTIMEDB_HTTP_PROTOCOL optional HTTP protocol for pipeline/dashboard API (http or https), defaults to http.

GREPTIMEDB_POOL_SIZE optional Connection pool size, defaults to 5.

GREPTIMEDB_MASK_ENABLED optional Enable sensitive data masking, defaults to true.

GREPTIMEDB_MASK_PATTERNS optional Additional masking column-name patterns, comma-separated.

GREPTIMEDB_AUDIT_ENABLED optional Enable audit logging for tool invocations, defaults to true.

GREPTIMEDB_ALLOW_WRITE optional Allow write/destructive SQL via execute_sql (dangerous, local/test only), defaults to false.

GREPTIMEDB_TRANSPORT optional Transport mode: stdio, sse, or streamable-http.

GREPTIMEDB_LISTEN_HOST optional HTTP server bind host, defaults to 0.0.0.0.

GREPTIMEDB_LISTEN_PORT optional HTTP server bind port, defaults to 8080.

GREPTIMEDB_ALLOWED_HOSTS optional Allowed hosts for DNS rebinding protection, comma-separated.

GREPTIMEDB_ALLOWED_ORIGINS optional CORS allowed origins, comma-separated.

Install: pip install greptimedb-mcp-server.
Run (connects to localhost:4002 by default): greptimedb-mcp-server --host localhost --database public.
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"
      ]
    }
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

{
  "servers": {
    "greptimedb": {
      "command": "greptimedb-mcp-server",
      "args": [
        "--host",
        "localhost",
        "--database",
        "public"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add greptimedb -- greptimedb-mcp-server --host localhost --database public

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

The greptimedb server's tools (execute_sql, health_check, etc.) should appear in the client's tool list; ask the AI to run health_check — a response with connection status and server version confirms the install works.

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.

Things to try

Once connected, you can ask your AI assistant things like:

Show the latest 10 rows from the cpu table and check the connection health
Analyze the last hour of metrics trends with a TQL query
Create a new pipeline for log ingestion and dry-run it with sample data
Explain the execution plan of this SQL query

Tools 13

execute_sql read-only

Execute SQL queries with format (csv/json/markdown) and limit options.

execute_tql read-only

Execute TQL (PromQL-compatible) queries for time-series analysis.

query_range read-only

Execute time-window aggregation queries with RANGE/ALIGN syntax.

describe_table read-only

Inspect table profile: schema, semantic metadata, latest sample rows, and query guidance.

explain_query read-only

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 read-only

Check database connection status and server version.

list_pipelines read-only

List all pipelines or get details of a specific pipeline.

create_pipeline writes

Create a new pipeline with YAML configuration.

Show 5 more tools

dryrun_pipeline read-only

Test a pipeline with sample data without writing to database.

delete_pipeline destructive

Delete a specific version of a pipeline.

list_dashboards read-only

List all Perses dashboard definitions.

create_dashboard writes

Create or update a Perses dashboard definition.

delete_dashboard destructive

Delete a dashboard definition.

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 Desktop

Listed from the project's documentation, not tested by this site.

Overview

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.

Similar servers

MCP ClickHouse 79 · B

Connect ClickHouse to your AI assistants

★ 889 · Tools 4 Compare with this →

ChEMBL MCP Server 75 · B

Unofficial MCP server providing advanced access to the ChEMBL chemical database

★ 89 · Tools 27 Compare with this →

MCP Toolbox for Databases 74 · B

Google's official database MCP toolbox — define AI-accessible database tools via config

★ 16.7k Compare with this →

DBHub 74 · B

Bytebase's official, minimalist two-tool database MCP server

★ 3.7k · Tools 2 Compare with this →

Compare with other MCP servers

Source revision 5347e7e38002 Data synced 2026-10-19 Read the FMRS scoring method