GreptimeDB

greptimedb-mcp-server

Server Model Context Protocol (MCP) untuk GreptimeDB — database observabilitas sumber terbuka yang menangani metrik, log, dan jejak (traces) 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 mode baca-saja dan penyamaran 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

Perkakas

Perkakas	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
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.

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, perkakas tidak ditawarkan dan alasannya dicatat. Jendela waktunya wajib dan setengah terbuka, [start_time, end_time) selama observed_at, dan baris diagregasi di seluruh bucket observasi 60 detik dalam jendela tersebut.

Manajemen Pipeline

Perkakas	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 Dasbor

Perkakas	Deskripsi
list_dashboards	Daftarkan semua definisi dasbor Perses
create_dashboard	Buat atau perbarui definisi dasbor Perses
delete_dashboard	Hapus definisi dasbor

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.

Perkakas ini mencakup kueri dan pengelolaan data di GreptimeDB yang sudah ada. Untuk deployment, konfigurasi server, protokol penulisan, 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 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)

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 Baca-Saja (Direkomendasikan)

Buat pengguna baca-saja di GreptimeDB menggunakan penyedia pengguna statis:

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 baca-saja secara default. Untuk pengembangan lokal atau pengujian, Anda dapat mengizinkan SQL tulis/destruktif (DDL/DML seperti CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) melalui perkakas execute_sql dengan mengaktifkan mode tulis:

# 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.

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

Penyamaran Data

Kolom sensitif otomatis disamarkan (******) 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 perkakas 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