GreptimeDB

greptimedb-mcp-server

GreptimeDB के लिए एक Model Context Protocol (MCP) सर्वर — एक ओपन-सोर्स ऑब्ज़र्वेबिलिटी डेटाबेस जो मेट्रिक्स, लॉग्स और ट्रेस को एक ही इंजन में संभालता है।

AI सहायकों को SQL, TQL (PromQL-संगत), और RANGE क्वेरी का उपयोग करके GreptimeDB को क्वेरी और विश्लेषण करने में सक्षम बनाता है, जिसमें रीड-ओनली प्रवर्तन और डेटा मास्किंग जैसी अंतर्निहित सुरक्षा सुविधाएँ शामिल हैं।

त्वरित आरंभ

# Install
pip install greptimedb-mcp-server

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

Claude Desktop के लिए, अपने कॉन्फ़िग में यह जोड़ें (macOS पर ~/Library/Application Support/Claude/claude_desktop_config.json):

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

विशेषताएँ

उपकरण

उपकरण	विवरण
execute_sql	फ़ॉर्मेट (csv/json/markdown) और सीमा विकल्पों के साथ SQL क्वेरी निष्पादित करें
execute_tql	समय-श्रृंखला विश्लेषण के लिए TQL (PromQL-संगत) क्वेरी निष्पादित करें
query_range	RANGE/ALIGN सिंटैक्स के साथ समय-विंडो एग्रीगेशन क्वेरी निष्पादित करें
search_table_semantics	ऑब्ज़र्वेबिलिटी अवधारणा द्वारा तालिकाएँ खोजें, मिलान किए गए शब्दों द्वारा रैंक की गईं; तालिका नाम, सिमेंटिक विकल्प और एंटिटी घोषणाएँ खोजता है। schema खोजने के लिए डेटाबेस का चयन करता है
query_semantic_graph	सिमेंटिक ग्राफ़ क्वेरी करें: summary (इसमें क्या है), entities (नोड्स), relationships (एजेस) एक आवश्यक समय विंडो पर
describe_table	तालिका प्रोफ़ाइल का निरीक्षण करें: स्कीमा, सिमेंटिक मेटाडेटा, नवीनतम नमूना पंक्तियाँ और क्वेरी मार्गदर्शन
explain_query	SQL या TQL क्वेरी निष्पादन योजनाओं का विश्लेषण करें (रनटाइम आँकड़ों के लिए analyze=true; प्रति-पार्टीशन स्कैन मेट्रिक्स और इंडेक्स-प्रूनिंग काउंटरों के लिए analyze=true के साथ verbose=true जोड़ें)
health_check	डेटाबेस कनेक्शन स्थिति और सर्वर संस्करण जाँचें

search_table_semantics और describe_table में सिमेंटिक मेटाडेटा information_schema.table_semantics पढ़ते हैं। एक तालिका वहाँ दिखाई देती है जब उसमें greptime.semantic.* विकल्प होता है या एक अंतर्निहित परंपरा उसके लिए एंटिटी घोषणा प्राप्त करती है; अन्य तालिकाएँ अनुपस्थित रहती हैं। सर्वर व्यू की कॉलम सूची को प्रति प्रक्रिया एक बार पढ़ता है और केवल उन कॉलमों का चयन करता है जिन्हें यह उजागर करता है। entity_declarations के लिए GreptimeDB 1.3 आवश्यक है; पुराने संस्करणों पर इसे खाली घोषणा सेट के बजाय लापता कॉलम के रूप में रिपोर्ट किया जाता है।

उपकरण परिणाम GREPTIMEDB_MAX_RESULT_BYTES (डिफ़ॉल्ट 1048576, या 1 MiB) द्वारा सीमित होते हैं। बजट से अधिक क्वेरी परिणाम कम पंक्तियाँ लौटाता है और इसे truncated और truncation_reason में रिपोर्ट करता है; जिस परिणाम में हटाने के लिए कोई पंक्तियाँ नहीं होतीं, उसे अंत में एक सूचना के साथ काट दिया जाता है। बजट एक बहुत बड़े परिणाम के उपभोग के विरुद्ध एक सुरक्षा जाल है, इसलिए इसे कम करें यदि आपका MCP क्लाइंट उस तक पहुँचने से पहले परिणाम अस्वीकार कर देता है।

क्रॉस-डेटाबेस क्वेरी

सर्वर एक डेटाबेस से जुड़ता है, लेकिन पढ़ना उसी तक सीमित नहीं है:

उपकरण	दूसरे डेटाबेस तक कैसे पहुँचें
execute_sql, query_range, describe_table	तालिका को schema.table के रूप में योग्य बनाएं
execute_tql	metric{__schema__="other_db"}, जो केवल = स्वीकार करता है
search_table_semantics	schema पास करें
query_semantic_graph	पहले से ही कैटलॉग-व्यापी; कोई स्कोपिंग आवश्यक नहीं

कनेक्टेड खाते को लक्ष्य डेटाबेस पर पढ़ने की अनुमति की आवश्यकता होती है। उन्हें सूचीबद्ध करने के लिए SHOW DATABASES का उपयोग करें।

query_semantic_graph greptime_private.semantic_entities और greptime_private.semantic_relationships पढ़ता है, जिनके लिए GreptimeDB 1.3 आवश्यक है। स्टार्टअप पर सर्वर जाँचता है कि दोनों व्यू मौजूद हैं, उन कॉलमों को ले जाते हैं जिन्हें यह पढ़ता है, और कनेक्टेड खाते द्वारा पठनीय हैं; जब वे नहीं होते हैं, तो उपकरण पेश नहीं किया जाता है और कारण लॉग किया जाता है। इसकी समय विंडो आवश्यक और आधी-खुली है, [start_time, end_time) पर observed_at, और पंक्तियाँ उस विंडो में 60-सेकंड के अवलोकन बकेटों में एकत्रित की जाती हैं।

पाइपलाइन प्रबंधन

उपकरण	विवरण
list_pipelines	सभी पाइपलाइनों को सूचीबद्ध करें या किसी विशिष्ट पाइपलाइन का विवरण प्राप्त करें
create_pipeline	YAML कॉन्फ़िगरेशन के साथ एक नई पाइपलाइन बनाएं
dryrun_pipeline	डेटाबेस में लिखे बिना नमूना डेटा के साथ पाइपलाइन का परीक्षण करें
delete_pipeline	पाइपलाइन के किसी विशिष्ट संस्करण को हटाएं

डैशबोर्ड प्रबंधन

उपकरण	विवरण
list_dashboards	सभी Perses डैशबोर्ड परिभाषाएँ सूचीबद्ध करें
create_dashboard	Perses डैशबोर्ड परिभाषा बनाएं या अपडेट करें
delete_dashboard	डैशबोर्ड परिभाषा हटाएं

संसाधन और प्रॉम्प्ट

• संसाधन: greptime://<table>/data URI के माध्यम से तालिकाएँ ब्राउज़ करें
• प्रॉम्प्ट: सामान्य कार्यों के लिए अंतर्निहित Jinja टेम्पलेट — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

LLM एकीकरण और प्रॉम्प्ट उपयोग के लिए, docs/llm-instructions.md देखें।

ये उपकरण मौजूदा GreptimeDB में डेटा क्वेरी और प्रबंधन को कवर करते हैं। परिनियोजन, सर्वर कॉन्फ़िगरेशन, लेखन प्रोटोकॉल, पाइपलाइन सिंटैक्स, स्कीमा डिज़ाइन और प्रदर्शन निदान के लिए, सहायक को https://docs.greptime.com/SKILL.md पर GreptimeDB कौशल सूचकांक पर इंगित करें।

कॉन्फ़िगरेशन

पर्यावरण चर

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)

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

HTTP सर्वर मोड

कंटेनरीकृत या 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

DNS रीबाइंडिंग सुरक्षा

डिफ़ॉल्ट रूप से, DNS रीबाइंडिंग सुरक्षा प्रॉक्सी, गेटवे और Kubernetes सेवाओं के साथ संगतता के लिए अक्षम है। इसे सक्षम करने के लिए, --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

यदि आपको 421 Invalid Host Header त्रुटियाँ मिलती हैं, तो या तो सुरक्षा अक्षम करें (डिफ़ॉल्ट) या अपने होस्ट को अनुमत सूची में जोड़ें।

सुरक्षा

रीड-ओनली डेटाबेस उपयोगकर्ता (अनुशंसित)

स्टैटिक उपयोगकर्ता प्रदाता का उपयोग करके GreptimeDB में एक रीड-ओनली उपयोगकर्ता बनाएं:

mcp_readonly:readonly=your_secure_password

एप्लिकेशन-स्तरीय सुरक्षा गेट

सभी क्वेरी एक सुरक्षा गेट से गुजरती हैं जो:

• अवरुद्ध करता है: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• अवरुद्ध करता है: एन्कोडेड बायपास प्रयास (hex, UNHEX, CHAR)
• अनुमति देता है: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

लेखन मोड (डिफ़ॉल्ट रूप से अक्षम)

सर्वर डिफ़ॉल्ट रूप से रीड-ओनली है। लेखन मोड हर उस ऑपरेशन को सक्षम करता है जो संग्रहीत स्थिति को बदलता है:

• execute_sql के माध्यम से विनाशकारी SQL (DDL/DML जैसे CREATE, DROP, ALTER, INSERT, UPDATE, DELETE)
• 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

सक्षम होने पर, सुरक्षा गेट execute_sql के लिए बायपास हो जाता है, और सर्वर स्टार्टअप पर एक चेतावनी लॉग करता है। लेखन मोड बंद होने पर, वे चार उपकरण सर्वर से संपर्क किए बिना एक त्रुटि लौटाते हैं; list_pipelines, list_dashboards और dryrun_pipeline रीड-ओनली हैं और उपलब्ध रहते हैं।

⚠️ खतरा: यह एक AI सहायक को आपके डेटाबेस के विरुद्ध विनाशकारी कथन चलाने देता है। इसे उत्पादन डेटा के विरुद्ध कभी सक्षम न करें। यदि आपको केवल पढ़ने की पहुँच चाहिए तो रीड-ओनली डेटाबेस उपयोगकर्ता के साथ संयोजित करें।

डेटा मास्किंग

संवेदनशील कॉलम कॉलम नाम पैटर्न के आधार पर स्वचालित रूप से मास्क किए जाते हैं (******):

• प्रमाणीकरण: password, secret, token, api_key, credential
• वित्तीय: credit_card, cvv, bank_account
• व्यक्तिगत: ssn, id_card, passport

कस्टम पैटर्न जोड़ने के लिए --mask-patterns phone,email के साथ कॉन्फ़िगर करें।

ऑडिट लॉगिंग

सभी उपकरण आह्वान लॉग किए जाते हैं:

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 के साथ अक्षम करें।

विकास

# 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

लाइसेंस

MIT लाइसेंस - LICENSE.md देखें।

स्वीकृति

इनसे प्रेरित:

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