# Greptimedb Mcp Server

> Query and analyze GreptimeDB metrics, logs and traces via SQL, TQL and RANGE queries.

- **Type:** MCP server
- **Install:** `agentstack add mcp-greptimeteam-greptimedb-mcp-server`
- **Verified:** Pending review
- **Seller:** [GreptimeTeam](https://agentstack.voostack.com/s/greptimeteam)
- **Installs:** 0
- **Latest version:** 0.4.7
- **License:** MIT
- **Upstream author:** [GreptimeTeam](https://github.com/GreptimeTeam)
- **Source:** https://github.com/GreptimeTeam/greptimedb-mcp-server

## Install

```sh
agentstack add mcp-greptimeteam-greptimedb-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# greptimedb-mcp-server

[](https://pypi.org/project/greptimedb-mcp-server/)

[](https://registry.modelcontextprotocol.io/?q=io.github.GreptimeTeam%2Fgreptimedb-mcp-server)
[](LICENSE.md)

A Model Context Protocol (MCP) server for [GreptimeDB](https://github.com/GreptimeTeam/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
# Install
pip install greptimedb-mcp-server

# Run (connects to localhost:4002 by default)
greptimedb-mcp-server --host localhost --database public
```

For Claude Desktop, add this to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

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

## Features

### Tools

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

### Pipeline Management

| Tool | Description |
|------|-------------|
| `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 |

### Dashboard Management

| Tool | Description |
|------|-------------|
| `list_dashboards` | List all Perses dashboard definitions |
| `create_dashboard` | Create or update a Perses dashboard definition |
| `delete_dashboard` | Delete a dashboard definition |

### Resources & Prompts

- **Resources**: Browse tables via `greptime:///data` URIs
- **Prompts**: Built-in Jinja templates for common tasks — `pipeline_creator`, `log_pipeline`, `metrics_analysis`, `promql_analysis`, `trace_analysis`, `table_operation`, `schema_design_advisor`, `observability_correlation`, `ingestion_troubleshooting`, `query_performance_tuning`

For LLM integration and prompt usage, see [docs/llm-instructions.md](docs/llm-instructions.md).

## Configuration

### Environment Variables

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

# Optional
GREPTIMEDB_HTTP_PORT=4000      # HTTP API port for pipeline/dashboard management
GREPTIMEDB_HTTP_PROTOCOL=http  # HTTP protocol (http/https)
GREPTIMEDB_POOL_SIZE=5         # Connection pool size
GREPTIMEDB_MASK_ENABLED=true   # Enable sensitive data masking
GREPTIMEDB_MASK_PATTERNS=      # Additional patterns (comma-separated)
GREPTIMEDB_AUDIT_ENABLED=true  # Enable audit logging
GREPTIMEDB_ALLOW_WRITE=false   # Allow write/DDL via execute_sql (DANGEROUS, local/test only)

# Transport (for HTTP server mode)
GREPTIMEDB_TRANSPORT=stdio     # stdio, sse, or streamable-http
GREPTIMEDB_LISTEN_HOST=0.0.0.0 # HTTP server bind host
GREPTIMEDB_LISTEN_PORT=8080    # HTTP server bind port
GREPTIMEDB_ALLOWED_HOSTS=      # DNS rebinding protection (comma-separated)
GREPTIMEDB_ALLOWED_ORIGINS=    # CORS allowed origins (comma-separated)
```

### CLI Arguments

```bash
greptimedb-mcp-server \
  --host localhost \
  --port 4002 \
  --database public \
  --user root \
  --password "" \
  --timezone UTC \
  --pool-size 5 \
  --mask-enabled true \
  --allow-write false \
  --transport stdio
```

### HTTP Server Mode

For containerized or Kubernetes deployments. Requires `mcp>=1.8.0`:

```bash
# Streamable HTTP (recommended for production)
greptimedb-mcp-server --transport streamable-http --listen-port 8080

# SSE mode (legacy)
greptimedb-mcp-server --transport sse --listen-port 3000
```

#### DNS Rebinding Protection

By default, DNS rebinding protection is **disabled** for compatibility with proxies, gateways, and Kubernetes services. To enable it, use `--allowed-hosts`:

```bash
# Enable DNS rebinding protection with allowed hosts
greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "localhost:*,127.0.0.1:*,my-service.namespace:*"

# With custom allowed origins for CORS
greptimedb-mcp-server --transport streamable-http \
  --allowed-hosts "my-service.namespace:*" \
  --allowed-origins "http://localhost:*,https://my-app.example.com"

# Or via environment variables
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.

## Security

### Read-Only Database User (Recommended)

Create a read-only user in GreptimeDB using [static user provider](https://docs.greptime.com/user-guide/deployments-administration/authentication/static/#permission-modes):

```
mcp_readonly:readonly=your_secure_password
```

### Application-Level Security Gate

All queries go through a security gate that:
- **Blocks**: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
- **Blocks**: Encoded bypass attempts (hex, UNHEX, CHAR)
- **Allows**: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

### Write Mode (Disabled by Default)

The server is **read-only by default**. For local development or testing, you can
allow write/destructive SQL (DDL/DML such as `CREATE`, `DROP`, `ALTER`, `INSERT`,
`UPDATE`, `DELETE`) through the `execute_sql` tool by enabling write mode:

```bash
# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

# Or CLI argument
greptimedb-mcp-server --allow-write true
```

When enabled, the security gate is **bypassed** for `execute_sql`, and the server
logs a warning on startup.

> ⚠️ **Danger**: This lets an AI assistant run destructive statements against your
> database. Never enable it against production data. Combine with a read-only
> database user if you only need read access.

### Data Masking

Sensitive columns are automatically masked (`******`) based on column name patterns:
- Authentication: `password`, `secret`, `token`, `api_key`, `credential`
- Financial: `credit_card`, `cvv`, `bank_account`
- Personal: `ssn`, `id_card`, `passport`

Configure with `--mask-patterns phone,email` to add custom patterns.

### Audit Logging

All tool invocations are logged:

```
2025-12-10 10:30:45 - greptimedb_mcp_server.audit - INFO - [AUDIT] execute_sql | query="SELECT * FROM cpu LIMIT 10" | success=True | duration_ms=45.2
```

Disable with `--audit-enabled false`.

## Development

```bash
# Clone and setup
git clone https://github.com/GreptimeTeam/greptimedb-mcp-server.git
cd greptimedb-mcp-server
uv venv && source .venv/bin/activate
uv sync

# Run tests
pytest

# Format & lint
uv run black .
uv run flake8 src

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector uv --directory . run -m greptimedb_mcp_server.server
```

## License

MIT License - see [LICENSE.md](LICENSE.md).

## Acknowledgement

Inspired by:
- [ktanaka101/mcp-server-duckdb](https://github.com/ktanaka101/mcp-server-duckdb)
- [designcomputer/mysql_mcp_server](https://github.com/designcomputer/mysql_mcp_server)
- [mikeskarl/mcp-prompt-templates](https://github.com/mikeskarl/mcp-prompt-templates)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GreptimeTeam](https://github.com/GreptimeTeam)
- **Source:** [GreptimeTeam/greptimedb-mcp-server](https://github.com/GreptimeTeam/greptimedb-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.4.7** — security scan: pending review — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-greptimeteam-greptimedb-mcp-server
- Seller: https://agentstack.voostack.com/s/greptimeteam
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.