# GreptimeTeam/greptimedb-mcp-server [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/GreptimeTeam/greptimedb-mcp-server  
**GitHub Stars:** 29  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/greptimeteam-greptimedb-mcp-server

## Description
A Model Context Protocol (MCP) server for GreptimeDB

## Tools
Capabilities this server exposes over MCP:

- **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
- **search_table_semantics** — Find tables by observability concept, ranked by matched terms; searches table names, semantic options, and entity declarations
- **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 Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "greptimedb-mcp-server": {
    "command": "npx",
    "args": ["-y","@modelcontextprotocol/inspector"]
  }
}
```

## Documentation

## What GreptimeTeam/greptimedb-mcp-server MCP server does

GreptimeTeam/greptimedb-mcp-server MCP server exposes GreptimeDB capabilities through the Model Context Protocol. It is intended for databases containing observability data such as metrics, logs, and traces. Agents can query data with SQL, TQL, or GreptimeDB range syntax, inspect table structure and semantic metadata, review query plans, and check database connectivity.

The server also covers selected operational workflows. Its tools can list, create, test, and delete pipelines, as well as list, create, update, and delete Perses dashboard definitions. A table-data resource uses `greptime://<table>/data` URIs, and built-in Jinja prompts support tasks including metrics analysis, PromQL analysis, trace analysis, schema design, ingestion troubleshooting, and query tuning.

## How it works

After installation, the `greptimedb-mcp-server` executable connects to GreptimeDB using the configured host, port, database, user, and password. The default transport is stdio, which suits desktop MCP clients. HTTP deployments can use streamable HTTP or the legacy SSE mode, with configurable bind settings, CORS origins, and allowed hosts.

`execute_sql` accepts output formatting and row-limit options. `execute_tql` handles PromQL-compatible time-series queries, while `query_range` supports time-window aggregation with RANGE and ALIGN syntax. `explain_query` can return runtime analysis and, when verbose analysis is enabled, per-partition scan and index-pruning information. Semantic discovery reads `information_schema.table_semantics`; entity declarations require GreptimeDB 1.3 or later.

## Setup and configuration

Install the Python package with:

```bash
pip install greptimedb-mcp-server
```

A basic local launch is:

```bash
greptimedb-mcp-server --host localhost --database public
```

Connection settings are available through CLI options or `GREPTIMEDB_*` environment variables. These include the database host, MySQL protocol port, credentials, database name, timezone, connection-pool size, HTTP API settings, transport, and HTTP listen settings. Pipeline and dashboard operations use the configured HTTP API port and protocol.

For Claude Desktop, configure the server command with arguments such as `--host localhost` and `--database public`. Container or Kubernetes deployments can select `--transport streamable-http` and a listen port. DNS rebinding protection is disabled by default, but allowed hosts and origins can be supplied when needed.

## Tools and capabilities

GreptimeTeam/greptimedb-mcp-server MCP server provides these documented tool groups:

- Querying: `execute_sql`, `execute_tql`, `query_range`, and `explain_query`.
- Inspection: `describe_table`, `search_table_semantics`, and `health_check`.
- Pipelines: `list_pipelines`, `create_pipeline`, `dryrun_pipeline`, and `delete_pipeline`.
- Dashboards: `list_dashboards`, `create_dashboard`, and `delete_dashboard`.
- Resources: browse table data through `greptime://<table>/data`.
- Prompts: reusable templates for observability analysis, operations, and database design.

## Limitations and notes

The server is read-only by default. Its application security gate blocks destructive or modifying SQL, including DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, and COPY, while allowing read and analysis statements such as SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, and UNION. Setting `GREPTIMEDB_ALLOW_WRITE=true` or the equivalent CLI option bypasses that gate for `execute_sql` and is intended only for local development or testing.

Sensitive values can be masked using built-in column-name patterns for credentials, financial data, and personal identifiers. Additional patterns are configurable. Tool invocations are audit-logged by default, and audit logging can be disabled. `entity_declarations` is unavailable on GreptimeDB versions before 1.3, where the field is reported as missing rather than empty.

_Full upstream README: https://allmcps.com/mcp/greptimeteam-greptimedb-mcp-server/readme_