GreptimeDB

greptimedb-mcp-server

Sebuah server Model Context Protocol (MCP) untuk GreptimeDB — database observabilitas sumber terbuka yang menangani metrik, log, dan jejak dalam satu mesin.

Memungkinkan asisten AI untuk melakukan kueri dan menganalisis GreptimeDB menggunakan SQL, TQL (kompatibel dengan PromQL), dan kueri RANGE, dengan fitur keamanan bawaan seperti penegakan read-only dan penyembunyian data.

Memulai Cepat

# Install
pip install greptimedb-mcp-server

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

Untuk Claude Desktop, tambahkan ini ke konfigurasi Anda (~/Library/Application Support/Claude/claude_desktop_config.json di macOS):

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

Fitur

Alat

Alat	Deskripsi
execute_sql	Jalankan kueri SQL dengan opsi format (csv/json/markdown) dan batas
execute_tql	Jalankan kueri TQL (kompatibel dengan PromQL) untuk analisis deret waktu
query_range	Jalankan kueri agregasi jendela waktu dengan sintaks RANGE/ALIGN
search_table_semantics	Temukan tabel berdasarkan konsep observabilitas, diurutkan berdasarkan istilah yang cocok; mencari nama tabel, opsi semantik, dan deklarasi entitas. schema memilih database yang akan dicari
query_semantic_graph	Kueri grafik semantik: summary (isi yang dikandungnya), entities (simpul), relationships (tepi) dalam jendela waktu yang diperlukan
describe_table	Periksa profil tabel: skema, metadata semantik, baris sampel terbaru, dan panduan kueri
explain_query	Analisis rencana eksekusi kueri SQL atau TQL (analyze=true untuk statistik runtime; tambahkan verbose=true bersama analyze=true untuk metrik pemindaian per-partisi dan penghitung pemangkasan indeks)
health_check	Periksa status koneksi database dan versi server

search_table_semantics dan metadata semantik di describe_table membaca information_schema.table_semantics. Sebuah tabel muncul di sana ketika tabel tersebut membawa opsi greptime.semantic.* atau konvensi bawaan menurunkan deklarasi entitas untuknya; tabel lain tidak ada. Server membaca daftar kolom tampilan sekali per proses dan hanya memilih kolom yang dieksposnya. entity_declarations memerlukan GreptimeDB 1.3; pada versi sebelumnya, ini dilaporkan sebagai kolom yang hilang, bukan sebagai kumpulan deklarasi kosong.

Hasil alat dibatasi oleh GREPTIMEDB_MAX_RESULT_BYTES (default 1048576, atau 1 MiB). Hasil kueri yang melebihi anggaran mengembalikan lebih sedikit baris dan melaporkannya di truncated dan truncation_reason; hasil tanpa baris yang dapat dibuang dipotong dengan pemberitahuan di akhir. Anggaran adalah pengaman terhadap hasil yang terlalu besar untuk dikonsumsi, jadi turunkan jika klien MCP Anda menolak hasil sebelum anggaran tercapai.

Kueri lintas database

Server terhubung ke satu database, tetapi pembacaan tidak dibatasi padanya:

Alat	Cara menjangkau database lain
execute_sql, query_range, describe_table	Kualifikasikan tabel sebagai schema.table
execute_tql	metric{__schema__="other_db"}, yang hanya menerima =
search_table_semantics	Berikan schema
query_semantic_graph	Sudah mencakup seluruh katalog; tidak perlu pembatasan cakupan

Akun yang terhubung memerlukan izin baca pada database target. Gunakan SHOW DATABASES untuk mencantumkannya.

query_semantic_graph membaca greptime_private.semantic_entities dan greptime_private.semantic_relationships, yang memerlukan GreptimeDB 1.3. Saat startup, server memeriksa bahwa kedua tampilan ada, membawa kolom yang dibacanya, dan dapat dibaca oleh akun yang terhubung; jika tidak, alat tidak ditawarkan dan alasannya dicatat. Jendela waktunya wajib dan setengah terbuka, [start_time, end_time) di atas observed_at, dan baris diagregasi di seluruh bucket observasi 60 detik dalam jendela tersebut.

Manajemen Pipeline

Alat	Deskripsi
list_pipelines	Daftarkan semua pipeline atau dapatkan detail pipeline tertentu
create_pipeline	Buat pipeline baru dengan konfigurasi YAML
dryrun_pipeline	Uji pipeline dengan data sampel tanpa menulis ke database
delete_pipeline	Hapus versi tertentu dari sebuah pipeline

Manajemen Dashboard

Alat	Deskripsi
list_dashboards	Daftarkan semua definisi dashboard Perses
create_dashboard	Buat atau perbarui definisi dashboard Perses
delete_dashboard	Hapus definisi dashboard

Sumber Daya & Prompt

• Sumber Daya: Jelajahi tabel melalui URI greptime://<table>/data
• Prompt: Template Jinja bawaan untuk tugas umum — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

Untuk integrasi LLM dan penggunaan prompt, lihat docs/llm-instructions.md.

Alat-alat ini mencakup kueri dan pengelolaan data di GreptimeDB yang ada. Untuk deployment, konfigurasi server, protokol tulis, sintaks pipeline, desain skema, dan diagnosis kinerja, arahkan asisten ke indeks keterampilan GreptimeDB di https://docs.greptime.com/SKILL.md.

Konfigurasi

Variabel Lingkungan

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)

Argumen 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

Mode Server HTTP

Untuk deployment kontainer atau 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

Perlindungan DNS Rebinding

Secara default, perlindungan DNS rebinding dinonaktifkan untuk kompatibilitas dengan proxy, gateway, dan layanan Kubernetes. Untuk mengaktifkannya, gunakan --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

Jika Anda mengalami kesalahan 421 Invalid Host Header, nonaktifkan perlindungan (default) atau tambahkan host Anda ke daftar yang diizinkan.

Keamanan

Pengguna Database Read-Only (Disarankan)

Buat pengguna read-only di GreptimeDB menggunakan static user provider:

mcp_readonly:readonly=your_secure_password

Gerbang Keamanan Tingkat Aplikasi

Semua kueri melewati gerbang keamanan yang:

• Memblokir: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• Memblokir: Upaya bypass terenkode (hex, UNHEX, CHAR)
• Mengizinkan: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Mode Tulis (Dinonaktifkan Secara Default)

Server read-only secara default. Mode tulis mengaktifkan setiap operasi yang mengubah status tersimpan:

• SQL destruktif (DDL/DML seperti CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) melalui execute_sql
• 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

Saat diaktifkan, gerbang keamanan dilewati untuk execute_sql, dan server mencatat peringatan saat startup. Dengan mode tulis nonaktif, empat alat tersebut mengembalikan kesalahan tanpa menghubungi server; list_pipelines, list_dashboards, dan dryrun_pipeline bersifat read-only dan tetap tersedia.

⚠️ Bahaya: Ini memungkinkan asisten AI menjalankan pernyataan destruktif terhadap database Anda. Jangan pernah mengaktifkannya terhadap data produksi. Kombinasikan dengan pengguna database read-only jika Anda hanya memerlukan akses baca.

Penyembunyian Data

Kolom sensitif otomatis disembunyikan (******) berdasarkan pola nama kolom:

• Autentikasi: password, secret, token, api_key, credential
• Keuangan: credit_card, cvv, bank_account
• Pribadi: ssn, id_card, passport

Konfigurasikan dengan --mask-patterns phone,email untuk menambahkan pola kustom.

Pencatatan Audit

Semua pemanggilan alat dicatat:

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

Nonaktifkan dengan --audit-enabled false.

Pengembangan

# 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

Lisensi

Lisensi MIT - lihat LICENSE.md.

Penghargaan

Terinspirasi oleh:

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