GreptimeDB

greptimedb-mcp-server

เซิร์ฟเวอร์ Model Context Protocol (MCP) สำหรับ GreptimeDB — ฐานข้อมูลเชิงสังเกตการณ์แบบโอเพนซอร์สที่จัดการเมตริก ล็อก และเทรซในเอนจินเดียว

ช่วยให้ผู้ช่วย AI สามารถสอบถามและวิเคราะห์ GreptimeDB โดยใช้ SQL, TQL (เข้ากันได้กับ PromQL) และคิวรี RANGE พร้อมด้วยคุณสมบัติด้านความปลอดภัยในตัว เช่น การบังคับให้อ่านอย่างเดียวและการปกปิดข้อมูล

เริ่มต้นอย่างรวดเร็ว

# Install
pip install greptimedb-mcp-server

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

สำหรับ Claude Desktop ให้เพิ่มสิ่งนี้ลงในคอนฟิกของคุณ (~/Library/Application Support/Claude/claude_desktop_config.json บน macOS):

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

คุณสมบัติ

เครื่องมือ

เครื่องมือ	คำอธิบาย
execute_sql	ดำเนินการคิวรี SQL พร้อมตัวเลือกฟอร์แมต (csv/json/markdown) และขีดจำกัด
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 สำหรับสถิติรันไทม์ เพิ่ม verbose=true ควบคู่กับ analyze=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	ลบนิยามแดชบอร์ด

ทรัพยากรและพรอมต์

• ทรัพยากร: เรียกดูตารางผ่าน URI greptime://<table>/data
• พรอมต์: เทมเพลต 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 ที่มีอยู่ สำหรับการปรับใช้ คอนฟิกเซิร์ฟเวอร์ โปรโตคอลการเขียน ไวยากรณ์ไปป์ไลน์ การออกแบบสคีมา และการวินิจฉัยประสิทธิภาพ ให้ชี้ผู้ช่วยไปที่ดัชนีทักษะ GreptimeDB ที่ https://docs.greptime.com/SKILL.md

คอนฟิก

ตัวแปรสภาพแวดล้อม

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 Rebinding

โดยค่าเริ่มต้น การป้องกัน DNS rebinding ถูก ปิดใช้งาน เพื่อความเข้ากันได้กับพร็อกซี เกตเวย์ และบริการ 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 โดยใช้ static user provider:

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

โหมดเขียน (ปิดใช้งานโดยค่าเริ่มต้น)

เซิร์ฟเวอร์ อ่านอย่างเดียวโดยค่าเริ่มต้น โหมดเขียนเปิดใช้งานทุกการดำเนินการที่ เปลี่ยนสถานะที่จัดเก็บ:

• SQL ที่ทำลายล้าง (DDL/DML เช่น CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) ผ่าน execute_sql
• 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