GreptimeDB MCP Server

resmi

AI asistanlarına GreptimeDB'deki verileri güvenli ve yapılandırılmış bir şekilde keşfetme ve analiz etme imkanı sağlar.

GitHub
27

Dokümantasyon

greptimedb-mcp-server

PyPI - Version build workflow MCP Registry MIT License

GreptimeDB için bir Model Bağlam Protokolü (MCP) sunucusu — metrikleri, logları ve izleri tek bir motorda işleyen açık kaynaklı bir gözlemlenebilirlik veritabanı.

Yapay zeka asistanlarının SQL, TQL (PromQL uyumlu) ve RANGE sorguları kullanarak GreptimeDB'yi sorgulamasını ve analiz etmesini sağlar; salt okunur zorunluluğu ve veri maskeleme gibi yerleşik güvenlik özellikleriyle birlikte.

Hızlı Başlangıç

# Install
pip install greptimedb-mcp-server

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

Claude Desktop için, bunu yapılandırmanıza ekleyin (macOS'ta ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Özellikler

Araçlar

AraçAçıklama
execute_sqlBiçim (csv/json/markdown) ve limit seçenekleriyle SQL sorguları yürütür
execute_tqlZaman serisi analizi için TQL (PromQL uyumlu) sorguları yürütür
query_rangeRANGE/ALIGN sözdizimi ile zaman penceresi toplama sorguları yürütür
describe_tableBir tablo profilini inceler: şema, anlamsal meta veriler, en son örnek satırlar ve sorgu rehberliği
explain_querySQL veya TQL sorgu yürütme planlarını analiz eder (çalışma zamanı istatistikleri için analyze=true; bölüm başına tarama metrikleri ve dizin budama sayaçları için analyze=true ile birlikte verbose=true ekleyin)
health_checkVeritabanı bağlantı durumunu ve sunucu sürümünü kontrol eder

Pipeline Yönetimi

AraçAçıklama
list_pipelinesTüm pipeline'ları listeler veya belirli bir pipeline'ın ayrıntılarını getirir
create_pipelineYAML yapılandırmasıyla yeni bir pipeline oluşturur
dryrun_pipelineVeritabanına yazmadan örnek verilerle bir pipeline'ı test eder
delete_pipelineBir pipeline'ın belirli bir sürümünü siler

Dashboard Yönetimi

AraçAçıklama
list_dashboardsTüm Perses dashboard tanımlarını listeler
create_dashboardBir Perses dashboard tanımı oluşturur veya günceller
delete_dashboardBir dashboard tanımını siler

Kaynaklar ve İstemler

  • Kaynaklar: greptime://<table>/data URI'leri aracılığıyla tablolara göz atın
  • İstemler: Yaygın görevler için yerleşik Jinja şablonları — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

LLM entegrasyonu ve istem kullanımı için docs/llm-instructions.md dosyasına bakın.

Yapılandırma

Ortam Değişkenleri

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 Argümanları

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 Sunucu Modu

Konteynerli veya Kubernetes dağıtımları için. mcp>=1.8.0 gerektirir:

# 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 Yeniden Bağlama Koruması

Varsayılan olarak, DNS yeniden bağlama koruması, proxy'ler, ağ geçitleri ve Kubernetes hizmetleriyle uyumluluk için devre dışıdır. Etkinleştirmek için --allowed-hosts kullanın:

# 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 hatalarıyla karşılaşırsanız, korumayı devre dışı bırakın (varsayılan) veya ana bilgisayarınızı izin verilenler listesine ekleyin.

Güvenlik

Salt Okunur Veritabanı Kullanıcısı (Önerilir)

Statik kullanıcı sağlayıcı kullanarak GreptimeDB'de salt okunur bir kullanıcı oluşturun:

mcp_readonly:readonly=your_secure_password

Uygulama Düzeyinde Güvenlik Kapısı

Tüm sorgular şunları yapan bir güvenlik kapısından geçer:

  • Engeller: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
  • Engeller: Kodlanmış atlatma girişimleri (hex, UNHEX, CHAR)
  • İzin verir: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Yazma Modu (Varsayılan Olarak Devre Dışı)

Sunucu varsayılan olarak salt okunurdur. Yerel geliştirme veya test için, yazma modunu etkinleştirerek execute_sql aracı üzerinden yazma/yıkıcı SQL'e (CREATE, DROP, ALTER, INSERT, UPDATE, DELETE gibi DDL/DML) izin verebilirsiniz:

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

# Or CLI argument
greptimedb-mcp-server --allow-write true

Etkinleştirildiğinde, güvenlik kapısı execute_sql için atlanır ve sunucu başlangıçta bir uyarı günlüğe kaydeder.

⚠️ Tehlike: Bu, bir yapay zeka asistanının veritabanınıza karşı yıkıcı ifadeler çalıştırmasına izin verir. Üretim verilerine karşı asla etkinleştirmeyin. Yalnızca okuma erişimine ihtiyacınız varsa salt okunur bir veritabanı kullanıcısıyla birleştirin.

Veri Maskeleme

Hassas sütunlar, sütun adı desenlerine göre otomatik olarak maskelenir (******):

  • Kimlik doğrulama: password, secret, token, api_key, credential
  • Finansal: credit_card, cvv, bank_account
  • Kişisel: ssn, id_card, passport

Özel desenler eklemek için --mask-patterns phone,email ile yapılandırın.

Denetim Günlüğü

Tüm araç çağrıları günlüğe kaydedilir:

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 ile devre dışı bırakın.

Geliştirme

# 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

Lisans

MIT Lisansı - LICENSE.md dosyasına bakın.

Teşekkür

Şunlardan ilham alınmıştır: