GreptimeDB

公式

AIアシスタントに、GreptimeDB内のデータを安全かつ構造化された方法で探索・分析する手段を提供します。

GitHub

このMCPを試すスポンサー

GreptimeDB MCPで何ができますか？

SQLクエリの実行 — execute_sqlを使用して、CSV、JSON、またはMarkdown形式の出力と行数制限を指定し、メトリクス、ログ、またはトレースを取得します。
時系列データの分析 — PromQL互換のクエリにはexecute_tqlを、時間ウィンドウの集計にはquery_rangeを使用します。
テーブルスキーマの調査 — describe_tableを通じて、列タイプ、サンプル行、およびクエリのガイダンスを取得します。
クエリパフォーマンスの最適化 — explain_queryで実行計画を要求し、必要に応じてランタイム統計やパーティションごとのスキャンメトリクスを追加します。
パイプラインの管理 — YAML設定を使用して、データ処理パイプラインの作成、テスト、一覧表示、または削除を行います。
ダッシュボードの処理 — Persesダッシュボード定義の一覧表示、作成、更新、または削除を行います。

ドキュメント

greptimedb-mcp-server

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`	フォーマット（csv/json/markdown）と制限オプションを指定して SQL クエリを実行します
`execute_tql`	時系列分析用に TQL（PromQL 互換）クエリを実行します
`query_range`	RANGE/ALIGN 構文を使用して時間枠集計クエリを実行します
`search_table_semantics`	可観測性の概念でテーブルを検索し、一致した用語でランク付けします。テーブル名、セマンティックオプション、エンティティ宣言を検索します
`query_semantic_graph`	セマンティックグラフをクエリします：`summary`（内容）、`entities`（ノード）、`relationships`（エッジ）を必須の時間枠にわたって取得します
`describe_table`	テーブルプロファイルを検査します：スキーマ、セマンティックメタデータ、最新のサンプル行、クエリガイダンス
`explain_query`	SQL または TQL クエリの実行計画を分析します（`analyze=true` はランタイム統計用。`verbose=true` を `analyze=true` と併用すると、パーティションごとのスキャンメトリクスとインデックスプルーニングカウンタを取得できます）
`health_check`	データベースの接続ステータスとサーバーバージョンを確認します

search_table_semantics と describe_table 内のセマンティックメタデータは information_schema.table_semantics を読み取ります。テーブルが greptime.semantic.* オプションを持つか、組み込みの規約がエンティティ宣言を導出する場合にのみテーブルが表示され、その他のテーブルは表示されません。サーバーはビューの列リストをプロセスごとに 1 回読み取り、公開する列のみを選択します。entity_declarations には GreptimeDB 1.3 が必要です。それ以前のバージョンでは、空の宣言セットとしてではなく、欠落した列として報告されます。

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 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 デプロイメントの場合：

# 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（CREATE、DROP、ALTER、INSERT、UPDATE、DELETE などの DDL/DML）を許可できます。書き込みモードを有効にします：

# 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 を参照してください。

謝辞

以下に触発されました：