home / mcp / greptimedb mcp server

Greptimedb MCP Server

A Model Context Protocol (MCP) server for GreptimeDB

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "greptimeteam-greptimedb-mcp-server": {
      "command": "greptimedb-mcp-server",
      "args": [
        "--host",
        "localhost",
        "--database",
        "public"
      ],
      "env": {
        "GREPTIMEDB_HOST": "localhost",
        "GREPTIMEDB_PORT": "4002",
        "GREPTIMEDB_USER": "root",
        "GREPTIMEDB_DATABASE": "public",
        "GREPTIMEDB_PASSWORD": "YOUR_PASSWORD",
        "GREPTIMEDB_TIMEZONE": "UTC",
        "GREPTIMEDB_HTTP_PORT": "4000",
        "GREPTIMEDB_POOL_SIZE": "5",
        "GREPTIMEDB_TRANSPORT": "stdio",
        "GREPTIMEDB_LISTEN_HOST": "0.0.0.0",
        "GREPTIMEDB_LISTEN_PORT": "8080",
        "GREPTIMEDB_MASK_ENABLED": "true",
        "GREPTIMEDB_ALLOWED_HOSTS": "localhost,127.0.0.1",
        "GREPTIMEDB_AUDIT_ENABLED": "true",
        "GREPTIMEDB_HTTP_PROTOCOL": "http",
        "GREPTIMEDB_MASK_PATTERNS": "phone,email",
        "GREPTIMEDB_ALLOWED_ORIGINS": "http://localhost"
      }
    }
  }
}

You are running an MCP server for GreptimeDB that enables AI assistants to query and analyze your data using SQL, TQL-compatible time queries, and RANGE queries, while enforcing security measures like read-only access and data masking. This server connects your client tools to GreptimeDB’s data and provides flexible query capabilities with built-in protections and observability.

How to use

To use the GreptimeDB MCP server, install the package, run the server locally, and connect your MCP client or editor. The server accepts a local runtime configuration and exposes an MCP endpoint that your tooling can reach to execute SQL, TQL, and range queries, as well as manage pipelines and inspect data schemas.

How to install

Prerequisites: Python and a working network environment. You will install the MCP server package, then run the server with your desired host and database.

pip install greptimedb-mcp-server

# Run the server locally (default port 4002, connect to localhost by default)
greptimedb-mcp-server --host localhost --database public

Available tools

execute_sql

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

execute_tql

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

query_range

Perform time-window aggregations using RANGE/ALIGN syntax.

describe_table

Return table schemas including column names, types, and constraints.

explain_query

Analyze SQL or TQL query execution plans to optimize performance.

health_check

Verify database connection and server version health.

list_pipelines

List all pipelines or retrieve details of a specific pipeline.

create_pipeline

Create a new pipeline from a YAML configuration.

dryrun_pipeline

Test a pipeline with sample data without writing to the database.

delete_pipeline

Delete a specific version of a pipeline.