trackmcp
Back to directory
GreptimeTeam

greptimedb-mcp-server

View on GitHub

A Model Context Protocol (MCP) server implementation for GreptimeDB

23 stars PythonAI & Machine Learning Updated Sep 20, 2025

Documentation

greptimedb-mcp-server

PyPI - Version
build workflow
MCP Registry
MIT License

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

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

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

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

ToolDescription
`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.

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, ⚠️ 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:

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

Acknowledgement

Inspired by:

Frequently asked questions

What is greptimedb-mcp-server?

greptimedb-mcp-server is A Model Context Protocol (MCP) server implementation for GreptimeDB

How do I install greptimedb-mcp-server?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is greptimedb-mcp-server open source?

Yes — it is hosted on GitHub at https://github.com/GreptimeTeam/greptimedb-mcp-server and has 23 stars.

Related MCP tools

All-Hands-AIopenhands

🙌 OpenHands: Code Less, Make More for the Model Context Protocol. Enhance AI assistants with powerful integrations. Python-based implementation.

64,677 Python
agentartificial-intelligencechatgpt+6
mem0aimem0

Universal memory layer for AI Agents; Announcing OpenMemory MCP - local and secure memory management. Python-based implementation.

42,646 Python
agentsaiai-agents+12
zhayujiechatgpt-on-wechat

基于大模型搭建的聊天机器人，同时支持 微信公众号、企业微信应用、飞书、钉钉 等接入，可选择ChatGPT/Claude/DeepSeek/文心一言/讯飞星火/通义千问/ Gemini/GLM-4/Kimi/LinkAI，能处理文本、语音和图片，访问操作系统和互联网，支持基于自有知识库进行定制企业智能客服。

39,573 Python
aiai-agentchatgpt+17
assafelovicgpt-researcher

An LLM agent that conducts deep research (local and web) on any given topic and generates a long report with citations. Built for the Model Context Protocol to

24,026 Python
agentaiautomation+8
jlowinfastmcp

🚀 The fast, Pythonic way to build MCP servers and clients Trusted by 19900+ developers. Trusted by 19900+ developers. Trusted by 19900+ developers.

19,927 Python
agentsfastmcpllms+6
1Panel-devmaxkb

🔥 MaxKB is an open-source platform for building enterprise-grade agents. MaxKB 是强大易用的开源企业级智能体平台。 for the Model Context Protocol. Enhance AI assistants with po

19,062 Python
agentagentic-aichatbot+11

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP