MCP.so
Sign In

greptimedb-mcp-server

@GreptimeTeam

Repository

About greptimedb-mcp-server

A Model Context Protocol (MCP) server for GreptimeDB

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "greptimedb-mcp-server": {
      "command": "uv",
      "args": [
        "venv",
        "&&",
        "source",
        ".venv/bin/activate"
      ]
    }
  }
}

Tools

6

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

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

Execute time-window aggregation queries with RANGE/ALIGN syntax

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

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)

Check database connection status and server version

Overview

What is greptimedb-mcp-server?

It is a Model Context Protocol (MCP) server for GreptimeDB, an open-source observability database that handles metrics, logs, and traces. It 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.

How to use greptimedb-mcp-server?

Install via pip install greptimedb-mcp-server, then run greptimedb-mcp-server --host localhost --database public. For Claude Desktop, add the MCP server configuration to your claude_desktop_config.json. The server can also be started in HTTP server mode for containerized deployments.

Key features of greptimedb-mcp-server

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

Use cases of greptimedb-mcp-server

  • Query and analyze observability metrics, logs, and traces with AI assistants.
  • Automate pipeline and dashboard management via MCP tools.
  • Debug and optimize queries by inspecting execution plans.
  • Enforce security policies (read-only, masking, audit) for AI-driven database access.

FAQ from greptimedb-mcp-server

Is the server read-only by default?

Yes. All queries pass through a security gate that blocks DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY, and encoded bypass attempts. Only SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, and UNION are allowed.

How can I enable write mode?

Set the environment variable GREPTIMEDB_ALLOW_WRITE=true or use the CLI argument --allow-write true. This bypasses the security gate for execute_sql and is intended only for local development or testing, never for production.

What transport modes are supported?

The server supports stdio (default), SSE (legacy), and streamable-http (recommended for production). Transport is set via the --transport CLI argument or GREPTIMEDB_TRANSPORT environment variable.

What are the runtime requirements?

A running GreptimeDB instance accessible via MySQL protocol (default port 4002) and optionally via HTTP (port 4000) for pipeline and dashboard management. Python with the installed package is required.

Can I use data masking with custom patterns?

Yes. Data masking is enabled by default for known sensitive column names. You can add custom patterns via --mask-patterns phone,email or the GREPTIMEDB_MASK_PATTERNS environment variable.

Frequently asked questions

Is the server read-only by default?

Yes. All queries pass through a security gate that blocks DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY, and encoded bypass attempts. Only SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, and UNION are allowed.

How can I enable write mode?

Set the environment variable `GREPTIMEDB_ALLOW_WRITE=true` or use the CLI argument `--allow-write true`. This bypasses the security gate for `execute_sql` and is intended only for local development or testing, never for production.

What transport modes are supported?

The server supports stdio (default), SSE (legacy), and streamable-http (recommended for production). Transport is set via the `--transport` CLI argument or `GREPTIMEDB_TRANSPORT` environment variable.

What are the runtime requirements?

A running GreptimeDB instance accessible via MySQL protocol (default port 4002) and optionally via HTTP (port 4000) for pipeline and dashboard management. Python with the installed package is required.

Can I use data masking with custom patterns?

Yes. Data masking is enabled by default for known sensitive column names. You can add custom patterns via `--mask-patterns phone,email` or the `GREPTIMEDB_MASK_PATTERNS` environment variable.

Comments

Basic information

Category

Other

License

MIT

Transports

stdio

Author

GreptimeTeam

More Other MCP servers

IDA Pro MCP

mrexodia

AI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.

9.9K

Mobile Mcp

mobile-next

Model Context Protocol Server for Mobile Automation and Scraping (iOS, Android, Emulators, Simulators and Real Devices)

5.4K

Peekaboo MCP – lightning-fast macOS screenshots for AI agents

steipete

Peekaboo is a macOS CLI & optional MCP server that enables AI agents to capture screenshots of applications, or the entire system, with optional visual question answering through local or remote AI models.

4.8K

Sequential Thinking

modelcontextprotocol

Model Context Protocol Servers

88.2K

Inbox Zero AI

elie222

The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.

11.6K