GreptimeDB MCP Server

resmi

Menyediakan asisten AI dengan cara yang aman dan terstruktur untuk menjelajahi serta menganalisis data di GreptimeDB.

GitHub
27

Dokumentasi

greptimedb-mcp-server

PyPI - Version build workflow MCP Registry MIT License

Server Model Context Protocol (MCP) untuk GreptimeDB — basis data observabilitas sumber terbuka yang menangani metrik, log, dan trace 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 penerapan hanya-baca dan penyamaran data.

Mulai 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

AlatDeskripsi
execute_sqlJalankan kueri SQL dengan opsi format (csv/json/markdown) dan batasan
execute_tqlJalankan kueri TQL (kompatibel dengan PromQL) untuk analisis deret waktu
query_rangeJalankan kueri agregasi jendela waktu dengan sintaks RANGE/ALIGN
describe_tablePeriksa profil tabel: skema, metadata semantik, baris sampel terbaru, dan panduan kueri
explain_queryAnalisis rencana eksekusi kueri SQL atau TQL (analyze=true untuk statistik waktu proses; tambahkan verbose=true bersama analyze=true untuk metrik pemindaian per-partisi dan penghitung pemangkasan indeks)
health_checkPeriksa status koneksi basis data dan versi server

Manajemen Pipeline

AlatDeskripsi
list_pipelinesDaftar semua pipeline atau dapatkan detail pipeline tertentu
create_pipelineBuat pipeline baru dengan konfigurasi YAML
dryrun_pipelineUji pipeline dengan data sampel tanpa menulis ke basis data
delete_pipelineHapus versi tertentu dari pipeline

Manajemen Dasbor

AlatDeskripsi
list_dashboardsDaftar semua definisi dasbor Perses
create_dashboardBuat atau perbarui definisi dasbor Perses
delete_dashboardHapus 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.

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 dalam kontainer atau Kubernetes. Memerlukan mcp>=1.8.0:

# 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 galat 421 Invalid Host Header, nonaktifkan perlindungan (default) atau tambahkan host Anda ke daftar yang diizinkan.

Keamanan

Pengguna Basis Data Hanya-Baca (Direkomendasikan)

Buat pengguna hanya-baca 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 yang disandikan (hex, UNHEX, CHAR)
  • Mengizinkan: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Mode Tulis (Dinonaktifkan secara Default)

Server hanya-baca secara default. Untuk pengembangan atau pengujian lokal, Anda dapat mengizinkan SQL tulis/destruktif (DDL/DML seperti CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) melalui alat 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 basis data Anda. Jangan pernah mengaktifkannya untuk data produksi. Gabungkan dengan pengguna basis data hanya-baca jika Anda hanya memerlukan akses baca.

Penyamaran Data

Kolom sensitif secara otomatis disamarkan (******) berdasarkan pola nama kolom:

  • Otentikasi: 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: