GreptimeDB MCP Server

greptimedb-mcp-server

一個用於 GreptimeDB 的模型上下文協定 (MCP) 伺服器 — GreptimeDB 是一個開源的可觀測性資料庫，能在單一引擎中處理指標、日誌和追蹤。

讓 AI 助理能夠使用 SQL、TQL（相容於 PromQL）和 RANGE 查詢來查詢和分析 GreptimeDB，並內建安全功能，例如強制唯讀和資料遮罩。

快速入門

# Install
pip install greptimedb-mcp-server

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

針對 Claude Desktop，請將以下內容新增至您的設定檔（在 macOS 上位於 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

功能特色

工具

工具	說明
`execute_sql`	執行 SQL 查詢，並提供格式（csv/json/markdown）和限制選項
`execute_tql`	執行 TQL（相容於 PromQL）查詢以進行時間序列分析
`query_range`	使用 RANGE/ALIGN 語法執行時間窗口聚合查詢
`describe_table`	檢查資料表設定檔：結構描述、語意中繼資料、最新的範例資料列以及查詢指引
`explain_query`	分析 SQL 或 TQL 查詢執行計畫（使用 `analyze=true` 取得執行階段統計資料；在 `analyze=true` 旁加上 `verbose=true` 以取得每個分割區的掃描指標和索引修剪計數器）
`health_check`	檢查資料庫連線狀態和伺服器版本

管線管理

工具	說明
`list_pipelines`	列出所有管線或取得特定管線的詳細資訊
`create_pipeline`	使用 YAML 設定建立新的管線
`dryrun_pipeline`	使用範例資料測試管線，而不寫入資料庫
`delete_pipeline`	刪除管線的特定版本

儀表板管理

工具	說明
`list_dashboards`	列出所有 Perses 儀表板定義
`create_dashboard`	建立或更新 Perses 儀表板定義
`delete_dashboard`	刪除儀表板定義

資源與提示

資源：透過 greptime://<table>/data URI 瀏覽資料表
提示：用於常見任務的內建 Jinja 範本 — pipeline_creator、log_pipeline、metrics_analysis、promql_analysis、trace_analysis、table_operation、schema_design_advisor、observability_correlation、ingestion_troubleshooting、query_performance_tuning

有關 LLM 整合和提示使用方式，請參閱 docs/llm-instructions.md。

設定

環境變數

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

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 伺服器模式

適用於容器化或 Kubernetes 部署。需要 mcp>=1.8.0：

# 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 重新綁定防護

預設情況下，為了與代理伺服器、閘道和 Kubernetes 服務相容，DNS 重新綁定防護是停用的。若要啟用它，請使用 --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

如果您遇到 421 Invalid Host Header 錯誤，請停用防護（預設值）或將您的主機新增至允許清單。

安全性

唯讀資料庫使用者（建議）

使用靜態使用者提供者在 GreptimeDB 中建立唯讀使用者：

mcp_readonly:readonly=your_secure_password

應用程式層級安全閘道

所有查詢都會經過一個安全閘道，它會：

封鎖：DROP、DELETE、TRUNCATE、UPDATE、INSERT、ALTER、CREATE、GRANT、REVOKE、EXEC、LOAD、COPY
封鎖：編碼的繞過嘗試（hex、UNHEX、CHAR）
允許：SELECT、SHOW、DESCRIBE、TQL、EXPLAIN、UNION

寫入模式（預設停用）

伺服器預設為唯讀。對於本機開發或測試，您可以透過啟用寫入模式，允許透過 execute_sql 工具執行寫入/破壞性 SQL（DDL/DML，例如 CREATE、DROP、ALTER、INSERT、 UPDATE、DELETE）：

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

啟用後，execute_sql 的安全閘道將被繞過，且伺服器會在啟動時記錄一則警告。

⚠️ 危險：這會讓 AI 助理能夠對您的資料庫執行破壞性陳述式。切勿在生產資料上啟用它。如果您只需要讀取權限，請搭配唯讀資料庫使用者使用。

資料遮罩

根據欄位名稱模式，敏感欄位會自動遮罩（******）：

驗證：password、secret、token、api_key、credential
財務：credit_card、cvv、bank_account
個人：ssn、id_card、passport

使用 --mask-patterns phone,email 進行設定以新增自訂模式。

稽核記錄

所有工具調用都會被記錄：

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

使用 --audit-enabled false 停用。

開發

# 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

授權

MIT 授權 - 請參閱 LICENSE.md。

致謝

靈感來源：

文件