GreptimeDB

greptimedb-mcp-server

GreptimeDB için bir Model Context Protocol (MCP) sunucusu — metrikleri, günlükleri ve izleri tek bir motor üzerinde işleyen açık kaynaklı bir gözlemlenebilirlik veritabanı.

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

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, yapılandırmanıza şunu 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_sql	Biçim (csv/json/markdown) ve limit seçenekleriyle SQL sorguları çalıştırın
execute_tql	Zaman serisi analizi için TQL (PromQL uyumlu) sorguları çalıştırın
query_range	RANGE/ALIGN sözdizimiyle zaman penceresi toplama sorguları çalıştırın
search_table_semantics	Gözlemlenebilirlik kavramına göre tabloları bulun, eşleşen terimlere göre sıralayın; tablo adlarını, anlamsal seçenekleri ve varlık bildirimlerini arar
query_semantic_graph	Anlamsal grafiği sorgulayın: summary (içerdikleri), entities (düğümler), relationships (kenarlar) gerekli bir zaman penceresi üzerinde
describe_table	Bir tablo profilini inceleyin: şema, anlamsal meta veriler, en son örnek satırlar ve sorgu rehberliği
explain_query	SQL veya TQL sorgu yürütme planlarını analiz edin (ç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_check	Veritabanı bağlantı durumunu ve sunucu sürümünü kontrol edin

search_table_semantics ve describe_table içindeki anlamsal meta veriler information_schema.table_semantics okur. Bir tablo, greptime.semantic.* seçeneği taşıdığında veya yerleşik bir kural onun için bir varlık bildirimi türettiğinde orada görünür; diğer tablolar yoktur. Sunucu, görünümün sütun listesini işlem başına bir kez okur ve yalnızca sunduğu sütunları seçer. entity_declarations, GreptimeDB 1.3 gerektirir; önceki sürümlerde boş bir bildirim kümesi yerine eksik sütun olarak raporlanır.

query_semantic_graph, greptime_private.semantic_entities ve greptime_private.semantic_relationships okur; bunlar GreptimeDB 1.3 gerektirir. Başlangıçta sunucu, her iki görünümün de var olduğunu, okuduğu sütunları taşıdığını ve bağlı hesap tarafından okunabilir olduğunu kontrol eder; bunlar mevcut değilse araç sunulmaz ve nedeni günlüğe kaydedilir. Zaman penceresi zorunludur ve yarı açıktır, observed_at üzerinde [start_time, end_time) ve satırlar, o penceredeki 60 saniyelik gözlem demetleri boyunca toplanır.

Pipeline Yönetimi

Araç	Açıklama
list_pipelines	Tüm pipeline'ları listeleyin veya belirli bir pipeline'ın ayrıntılarını alın
create_pipeline	YAML yapılandırmasıyla yeni bir pipeline oluşturun
dryrun_pipeline	Veritabanına yazmadan örnek verilerle bir pipeline'ı test edin
delete_pipeline	Bir pipeline'ın belirli bir sürümünü silin

Pano Yönetimi

Araç	Açıklama
list_dashboards	Tüm Perses pano tanımlarını listeleyin
create_dashboard	Bir Perses pano tanımı oluşturun veya güncelleyin
delete_dashboard	Bir pano tanımını silin

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 bölümüne bakın.

Bu araçlar, mevcut bir GreptimeDB'de veri sorgulamayı ve yönetmeyi kapsar. Dağıtım, sunucu yapılandırması, yazma protokolleri, pipeline sözdizimi, şema tasarımı ve performans teşhisi için asistanı https://docs.greptime.com/SKILL.md adresindeki GreptimeDB becerileri dizinine yönlendirin.

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 Bağımsız Değişkenleri

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

Kapsayıcılı veya Kubernetes dağıtımları için:

# 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ı (Önerilen)

statik kullanıcı sağlayıcısını 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 şu 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, execute_sql aracı aracılığıyla yazma/yıkıcı SQL'e (CREATE, DROP, ALTER, INSERT, UPDATE, DELETE gibi DDL/DML) izin vermek üzere yazma modunu etkinleştirebilirsiniz:

# 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 olanak tanır. Ü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 bölümüne bakın.

Teşekkür

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

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