GreptimeDB

官方

為AI助手提供安全且結構化的方式來探索和分析GreptimeDB中的數據。

GitHub
29

你可以用 GreptimeDB MCP 做什麼？

  • 執行 SQL 查詢 — 透過 execute_sql 要求資料檢索，並提供格式與列數限制選項，包括使用 schema.table 進行跨資料庫讀取。
  • 執行時間序列分析 — 使用 execute_tql 進行 PromQL 相容查詢，或使用 query_range 搭配 RANGE/ALIGN 語法進行時間視窗聚合。
  • 檢查資料表結構 — 透過 describe_table 取得結構描述、語意中繼資料、範例列與查詢指引，或使用 search_table_semantics 依可觀測性概念尋找資料表。
  • 分析查詢效能 — 透過 explain_query 要求 SQL 或 TQL 的執行計畫，可選擇包含執行時期統計資料與每個分割區的掃描指標。
  • 管理管線與儀表板 — 透過專屬管理工具列出、建立、測試或刪除管線與 Perses 儀表板。

文件

greptimedb-mcp-server

PyPI - Version build workflow MCP Registry MIT License

一個用於 GreptimeDB 的 Model Context Protocol (MCP) 伺服器——這是一個開源的可觀測性資料庫，可在單一引擎中處理指標、日誌和追蹤。

讓 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 語法執行時間視窗聚合查詢
search_table_semantics依可觀測性概念尋找資料表，按相符詞彙排序；搜尋資料表名稱、語意選項和實體宣告。schema 選擇要搜尋的資料庫
query_semantic_graph查詢語意圖：summary（包含的內容）、entities（節點）、relationships（邊），需在指定的時間視窗內
describe_table檢查資料表概況：結構描述、語意中繼資料、最新樣本列和查詢指引
explain_query分析 SQL 或 TQL 查詢執行計畫（analyze=true 用於執行時期統計；在 analyze=true 旁加上 verbose=true 可取得每個分割區的掃描指標和索引剪枝計數器）
health_check檢查資料庫連線狀態和伺服器版本

search_table_semantics 和 describe_table 中的語意中繼資料會讀取 information_schema.table_semantics。當資料表帶有 greptime.semantic.* 選項，或內建慣例為其推導出實體宣告時，該資料表才會出現在其中；其他資料表則不會出現。伺服器在每個處理程序啟動時讀取該檢視的欄位清單一次，並僅選取它所公開的欄位。entity_declarations 需要 GreptimeDB 1.3；在較早版本上，它會被回報為缺少欄位，而非空白的宣告集合。

工具結果受 GREPTIMEDB_MAX_RESULT_BYTES（預設 1048576，即 1 MiB）限制。超過預算的查詢結果會回傳較少的列數，並在 truncated 和 truncation_reason 中回報；若結果沒有可捨棄的列，則會在結尾加上通知來截斷。此預算是防止結果過大而無法被消費的最後防線，因此如果你的 MCP 用戶端在達到預算前就拒絕結果，請調低此值。

跨資料庫查詢

伺服器連線到一個資料庫，但讀取操作不受限於該資料庫：

工具如何存取另一個資料庫
execute_sql、query_range、describe_table將資料表限定為 schema.table
execute_tqlmetric{__schema__="other_db"}，僅接受 =
search_table_semantics傳入 schema
query_semantic_graph已是全目錄範圍；無需限定範圍

連線的帳號需要對目標資料庫具有讀取權限。使用 SHOW DATABASES 來列出它們。

query_semantic_graph 讀取 greptime_private.semantic_entities 和 greptime_private.semantic_relationships，這需要 GreptimeDB 1.3。在啟動時，伺服器會檢查這兩個檢視是否存在、是否帶有它讀取的欄位，以及連線的帳號是否可讀取；若不符合條件，該工具就不會被提供，並會記錄原因。其時間視窗是必填且半開放的，[start_time, end_time) 在 observed_at 之上，列會跨該視窗中的 60 秒觀測區間進行聚合。

管線管理

工具說明
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 中查詢和管理資料。如需部署、伺服器設定、寫入協定、管線語法、結構描述設計和效能診斷，請將助手指向位於 https://docs.greptime.com/SKILL.md 的 GreptimeDB 技能索引。

設定

環境變數

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 writes: DDL/DML plus pipeline and dashboard changes (DANGEROUS, local/test only)
GREPTIMEDB_MAX_RESULT_BYTES=1048576 # Byte budget for a single tool result (1 MiB)

# 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 部署：

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

預設情況下，DNS 重新綁定防護為停用，以相容於代理伺服器、閘道器和 Kubernetes 服務。若要啟用它，請使用 --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）
  • create_pipeline、delete_pipeline、create_dashboard、delete_dashboard
# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

啟用時，安全閘道會對 execute_sql 繞過，且伺服器會在啟動時記錄警告。當寫入模式關閉時，這四個工具會回傳錯誤而不會聯絡伺服器；list_pipelines、list_dashboards 和 dryrun_pipeline 是唯讀的，仍可使用。

⚠️ 危險：這會讓 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。

致謝

靈感來自：