GreptimeDB

by greptimeteam

23 stars

917 downloads

Not rated

GitHub

About

Enables AI interaction with GreptimeDB time-series databases through MySQL protocol for data exploration, analysis, and SQL query execution with built-in security protections.

Details

Author: greptimeteam
Repository: GreptimeTeam/greptimedb-mcp-server
GitHub stars: 23
Downloads: 917
License: MIT License
Categories: Developer Tools, Database, Other, Infrastructure, AI, Design, Search, Security, Frontend
Tags: #data-analysis

- Execute SQL, TQL, and time-window aggregation queries.
- Inspect table schemas and query execution plans.
- List, create, test, and delete pipelines.
- List, create, and delete Perses dashboards.
- Read-only security gate blocking destructive SQL by default.
- Automatic data masking for sensitive columns.
- Audit logging of all tool invocations.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name GreptimeDB

Command (node, npx, python, etc.) greptimedb-mcp-server
Arguments
- Argument 1 --host
- Argument 2 localhost
- Argument 3 --database
- Argument 4 public
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

{
    "mcpServers": {
        "greptimedb": {
            "env": {},
            "args": [
                "/c",
                "greptimedb-mcp-server",
                "--host",
                "localhost",
                "--database",
                "public"
            ],
            "command": "cmd"
        }
    }
}

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

{
    "mcpServers": {
        "greptimedb": {
            "env": {},
            "args": [
                "/c",
                "greptimedb-mcp-server",
                "--host",
                "localhost",
                "--database",
                "public"
            ],
            "command": "cmd"
        }
    }
}

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

{
    "mcpServers": {
        "greptimedb": {
            "env": {},
            "args": [
                "/c",
                "greptimedb-mcp-server",
                "--host",
                "localhost",
                "--database",
                "public"
            ],
            "command": "cmd"
        }
    }
}

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

{
    "mcpServers": {
        "greptimedb": {
            "env": {},
            "args": [
                "/c",
                "greptimedb-mcp-server",
                "--host",
                "localhost",
                "--database",
                "public"
            ],
            "command": "cmd"
        }
    }
}

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

{
    "mcpServers": {
        "greptimedb": {
            "env": {},
            "args": [
                "/c",
                "greptimedb-mcp-server",
                "--host",
                "localhost",
                "--database",
                "public"
            ],
            "command": "cmd"
        }
    }
}

JSON

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

From the repository

GREPTIMEDB_HOST=localhost      # Database host
GREPTIMEDB_PORT=4002           # MySQL protocol port (default: 4002)
GREPTIMEDB_USER=root           # Database user
GREPTIMEDB_PASSWORD=           # Database password
GREPTIMEDB_DATABASE=public     # Database name
GREPTIMEDB_TIMEZONE=UTC        # Session timezone
GREPTIMEDB_ALLOWED_HOSTS="localhost:,my-service.namespace:" \

GREPTIMEDB_ALLOWED_ORIGINS="http://localhost:*" \

  greptimedb-mcp-server --transport streamable-http

If you encounter 421 Invalid Host Header errors, either disable protection (default) or add your host to the allowed list.

GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server
uv venv && source .venv/bin/activate
uv sync

`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 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.

`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.

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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

{
    "env": [],
    "args": [
        "/c",
        "greptimedb-mcp-server",
        "--host",
        "localhost",
        "--database",
        "public"
    ],
    "command": "cmd"
}

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

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

execute_sql

execute_tql

query_range

describe_table

explain_query

health_check

list_pipelines

create_pipeline

dryrun_pipeline

delete_pipeline

list_dashboards

create_dashboard

delete_dashboard

Claude Desktop / Cursor

Linux

Macos

Windows

greptimedb-mcp-server

Quick Start

Install

More like this

Sequential Thinking

Redis

Sentry

Github

Filesystem

EverArt

`execute_sql`

`execute_tql`

`query_range`

`describe_table`

`explain_query`

`health_check`

`list_pipelines`

`create_pipeline`

`dryrun_pipeline`

`delete_pipeline`

`list_dashboards`

`create_dashboard`

`delete_dashboard`