# Greptimedb MCP Server (MCP server)

> Greptimedb MCP Server is an MCP server that adds cloud and DevOps tools to AI assistants such as Claude Desktop, Claude Code and Cursor. Query GreptimeDB metrics, logs and traces with SQL, TQL and RANGE. It has 29 GitHub stars, is released under the MIT license and runs locally with uvx 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.

## Key facts

| Fact | Value |
|---|---|
| Repository | https://github.com/GreptimeTeam/greptimedb-mcp-server |
| GitHub stars | 29 |
| License | MIT |
| Language | Python |
| Transport | stdio |
| Packages | pypi: greptimedb-mcp-server |
| Remote URL | none |
| Needs API key | yes |
| Official | yes |
| Works with | Claude Desktop, Claude Code, Cursor, VS Code |
| Category | Cloud & DevOps |
| Latest release | v0.6.0 (Sep 14, 2026) |
| Last commit | Sep 14, 2026 |
| MCP registry name | io.github.GreptimeTeam/greptimedb-mcp-server |

## Install

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "greptimedb-mcp-server": {
      "command": "uvx",
      "args": [
        "greptimedb-mcp-server"
      ],
      "env": {
        "GREPTIMEDB_PASSWORD": "your-value"
      }
    }
  }
}
```

Settings > Developer > Edit Config. macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\. Restart Claude Desktop afterwards.

### Claude Code

```sh
claude mcp add --env GREPTIMEDB_PASSWORD=your-value --transport stdio greptimedb-mcp-server -- uvx greptimedb-mcp-server
```

### Cursor (.cursor/mcp.json)

```json
{
  "mcpServers": {
    "greptimedb-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "greptimedb-mcp-server"
      ],
      "env": {
        "GREPTIMEDB_PASSWORD": "your-value"
      }
    }
  }
}
```

Project file; use ~/.cursor/mcp.json to enable it in every project.

### VS Code (.vscode/mcp.json)

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "greptimedb_password",
      "description": "GREPTIMEDB_PASSWORD",
      "password": true
    }
  ],
  "servers": {
    "greptimedb-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "greptimedb-mcp-server"
      ],
      "env": {
        "GREPTIMEDB_PASSWORD": "${input:greptimedb_password}"
      }
    }
  }
}
```

Config formats checked against the official docs on 2026-10-07.

## Environment variables

- `GREPTIMEDB_HOST`: GreptimeDB host address
- `GREPTIMEDB_PORT`: GreptimeDB MySQL protocol port (default: 4002)
- `GREPTIMEDB_USER`: Database username
- `GREPTIMEDB_PASSWORD` (secret): Database password
- `GREPTIMEDB_DATABASE`: Database name to connect to
- `GREPTIMEDB_TIMEZONE`: Session timezone (default: UTC)
- `GREPTIMEDB_POOL_SIZE`: Connection pool size (default: 5)
- `GREPTIMEDB_HTTP_PORT`: HTTP API port for pipeline/dashboard management (default: 4000)
- `GREPTIMEDB_HTTP_PROTOCOL`: HTTP protocol for pipeline/dashboard API: http or https (default: http)
- `GREPTIMEDB_MASK_ENABLED`: Enable sensitive data masking (default: true)
- `GREPTIMEDB_MASK_PATTERNS`: Additional column name patterns for data masking (comma-separated)
- `GREPTIMEDB_AUDIT_ENABLED`: Enable audit logging for tool invocations (default: true)
- `GREPTIMEDB_ALLOW_WRITE`: Allow write/destructive SQL (DDL/DML) via execute_sql by skipping the security gate. DANGEROUS: only use on local or test instances (default: false)

## Tools

- `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…
- `query_semantic_graph`: Query the semantic graph: summary (what it contains), entities (nodes), relationships (edges) over a required time…
- `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…
- `health_check`: Check database connection status and server version

## Similar MCP servers

- [Worldmonitor](https://appsgit.com/mcp-servers/worldmonitor): Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface. (87,920 stars, AGPL-3.0)
- [Netdata](https://appsgit.com/mcp-servers/netdata): Real-time infrastructure monitoring with metrics, logs, alerts, and ML-based anomaly detection. (80,817 stars, GPL-3.0, needs API key)
- [openstatus](https://appsgit.com/mcp-servers/openstatus): Manage monitors, status pages, incidents and maintenances in your openstatus workspace. (9,171 stars, AGPL-3.0, official)
- [MCP Server Cloudflare](https://appsgit.com/mcp-servers/mcp-server-cloudflare): Model Context Protocol (MCP) is a new, standardized protocol for managing context between large language models (LLMs) and external systems. (4,360 stars, Apache-2.0, official, needs API key)
- [Dagu](https://appsgit.com/mcp-servers/dagu): Self-hostable workflow orchestrator for teams whose main work isn't orchestration. (4,289 stars, GPL-3.0)
- [Azure MCP Server](https://appsgit.com/mcp-servers/azure-mcp-server): All Azure MCP tools to create a seamless connection between AI agents and Azure services. (3,738 stars, MIT, official)

---

Canonical page: https://appsgit.com/mcp-servers/greptimedb-mcp-server
Source: appsgit (https://appsgit.com), the app store for github. Data from the GitHub API, refreshed nightly.
Machine access: JSON API https://appsgit.com/api/v1/apps (OpenAPI: https://appsgit.com/openapi.json), MCP server https://mcp.appsgit.com/mcp, full index https://appsgit.com/llms-full.txt.