greptimedb-mcp-server

greptimedb-mcp-server

GreptimeDB 向けの Model Context Protocol（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	形式（csv/json/markdown）と上限のオプションを指定して SQL クエリを実行します
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 クライアントが上限に達する前に結果を拒否する場合は、値を小さくしてください。

データベース間クエリ

サーバーは1つのデータベースに接続しますが、読み取りはそのデータベースに限定されません。

ツール	別のデータベースへのアクセス方法
execute_sql、query_range、describe_table	テーブルを schema.table として修飾します
execute_tql	metric{__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 が必要です。起動時にサーバーは、両方のビューが存在し、読み取り対象の列を持ち、接続アカウントから読み取り可能であることを確認します。条件を満たさない場合、このツールは提供されず、その理由がログに記録されます。時間ウィンドウは必須であり、observed_at に対する半開区間 [start_time, end_time) です。このウィンドウ内の行は、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 内のデータのクエリと管理を対象としています。デプロイ、サーバー設定、書き込みプロトコル、パイプライン構文、スキーマ設計、パフォーマンス診断については、GreptimeDB のスキルインデックス https://docs.greptime.com/SKILL.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 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 リバインディング保護

プロキシ、ゲートウェイ、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（CREATE、DROP、ALTER、INSERT、UPDATE、DELETE などの DDL／DML）
• 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 のセキュリティゲートがバイパスされ、サーバーは起動時に警告を記録します。書き込みモードがオフの場合、これら4つのツールはサーバーに接続せずにエラーを返します。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 をご覧ください。

謝辞

以下に着想を得ています。

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