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

# 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):

{
  "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
search_table_semantics	Find tables by observability concept, ranked by matched terms; searches table names, semantic options, and entity declarations
query_semantic_graph	Query the semantic graph: summary (what it contains), entities (nodes), relationships (edges) over a required time window
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

search_table_semantics and the semantic metadata in describe_table read information_schema.table_semantics. A table appears there when it carries a greptime.semantic.* option or a built-in convention derives an entity declaration for it; other tables are absent. The server reads the view's column list once per process and selects only the columns it exposes. entity_declarations requires GreptimeDB 1.3; on earlier versions it is reported as a missing column rather than as an empty declaration set.

query_semantic_graph reads greptime_private.semantic_entities and greptime_private.semantic_relationships, which require GreptimeDB 1.3. At startup the server checks that both views exist, carry the columns it reads, and are readable by the connected account; when they are not, the tool is not offered and the reason is logged. Its time window is required and half-open, [start_time, end_time) over observed_at, and rows are aggregated across the 60-second observation buckets in that window.

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://<table>/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.

These tools cover querying and managing data in an existing GreptimeDB. For deployment, server configuration, write protocols, pipeline syntax, schema design, and performance diagnosis, point the assistant at the GreptimeDB skills index at https://docs.greptime.com/SKILL.md.

Configuration

Environment Variables

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

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:

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

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

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:

# 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

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

Acknowledgement

Inspired by:

• ktanaka101/mcp-server-duckdb
• designcomputer/mysql_mcp_server
• mikeskarl/mcp-prompt-templates