GreptimeDB

greptimedb-mcp-server

Một máy chủ Model Context Protocol (MCP) cho GreptimeDB — một cơ sở dữ liệu quan sát mã nguồn mở xử lý số liệu, nhật ký và dấu vết trong một công cụ duy nhất.

Cho phép các trợ lý AI truy vấn và phân tích GreptimeDB bằng SQL, TQL (tương thích PromQL) và truy vấn RANGE, với các tính năng bảo mật tích hợp như thực thi chỉ đọc và che giấu dữ liệu.

Bắt đầu nhanh

# Install
pip install greptimedb-mcp-server

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

Đối với Claude Desktop, hãy thêm phần này vào cấu hình của bạn (~/Library/Application Support/Claude/claude_desktop_config.json trên macOS):

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

Tính năng

Công cụ

Công cụ	Mô tả
execute_sql	Thực thi truy vấn SQL với định dạng (csv/json/markdown) và tùy chọn giới hạn
execute_tql	Thực thi truy vấn TQL (tương thích PromQL) để phân tích chuỗi thời gian
query_range	Thực thi truy vấn tổng hợp cửa sổ thời gian với cú pháp RANGE/ALIGN
search_table_semantics	Tìm bảng theo khái niệm quan sát, được xếp hạng theo các thuật ngữ khớp; tìm kiếm tên bảng, tùy chọn ngữ nghĩa và khai báo thực thể
query_semantic_graph	Truy vấn đồ thị ngữ nghĩa: summary (nội dung chứa), entities (các nút), relationships (các cạnh) trong một cửa sổ thời gian bắt buộc
describe_table	Kiểm tra hồ sơ bảng: lược đồ, siêu dữ liệu ngữ nghĩa, các hàng mẫu mới nhất và hướng dẫn truy vấn
explain_query	Phân tích kế hoạch thực thi truy vấn SQL hoặc TQL (analyze=true cho số liệu thời gian chạy; thêm verbose=true cùng với analyze=true cho số liệu quét theo phân vùng và bộ đếm cắt tỉa chỉ mục)
health_check	Kiểm tra trạng thái kết nối cơ sở dữ liệu và phiên bản máy chủ

search_table_semantics và siêu dữ liệu ngữ nghĩa trong describe_table đọc information_schema.table_semantics. Một bảng xuất hiện ở đó khi nó mang tùy chọn greptime.semantic.* hoặc một quy ước tích hợp suy ra khai báo thực thể cho nó; các bảng khác không có mặt. Máy chủ đọc danh sách cột của view một lần cho mỗi tiến trình và chỉ chọn các cột mà nó hiển thị. entity_declarations yêu cầu GreptimeDB 1.3; trên các phiên bản trước đó, nó được báo cáo là một cột bị thiếu thay vì là một tập khai báo trống.

query_semantic_graph đọc greptime_private.semantic_entities và greptime_private.semantic_relationships, yêu cầu GreptimeDB 1.3. Khi khởi động, máy chủ kiểm tra rằng cả hai view tồn tại, mang các cột mà nó đọc và có thể đọc được bởi tài khoản được kết nối; khi không đáp ứng, công cụ không được cung cấp và lý do được ghi nhật ký. Cửa sổ thời gian của nó là bắt buộc và nửa mở, [start_time, end_time) trên observed_at, và các hàng được tổng hợp qua các nhóm quan sát 60 giây trong cửa sổ đó.

Quản lý Pipeline

Công cụ	Mô tả
list_pipelines	Liệt kê tất cả pipeline hoặc lấy chi tiết của một pipeline cụ thể
create_pipeline	Tạo pipeline mới với cấu hình YAML
dryrun_pipeline	Kiểm tra pipeline với dữ liệu mẫu mà không ghi vào cơ sở dữ liệu
delete_pipeline	Xóa một phiên bản cụ thể của pipeline

Quản lý Dashboard

Công cụ	Mô tả
list_dashboards	Liệt kê tất cả định nghĩa dashboard Perses
create_dashboard	Tạo hoặc cập nhật định nghĩa dashboard Perses
delete_dashboard	Xóa định nghĩa dashboard

Tài nguyên & Lời nhắc

• Tài nguyên: Duyệt các bảng qua URI greptime://<table>/data
• Lời nhắc: Các mẫu Jinja tích hợp cho các tác vụ phổ biến — pipeline_creator, log_pipeline, metrics_analysis, promql_analysis, trace_analysis, table_operation, schema_design_advisor, observability_correlation, ingestion_troubleshooting, query_performance_tuning

Để tích hợp LLM và cách sử dụng lời nhắc, xem docs/llm-instructions.md.

Các công cụ này bao gồm việc truy vấn và quản lý dữ liệu trong một GreptimeDB hiện có. Để triển khai, cấu hình máy chủ, giao thức ghi, cú pháp pipeline, thiết kế lược đồ và chẩn đoán hiệu suất, hãy trỏ trợ lý đến chỉ mục kỹ năng GreptimeDB tại https://docs.greptime.com/SKILL.md.

Cấu hình

Biến môi trường

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)

Đối số 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

Chế độ máy chủ HTTP

Đối với triển khai containerized hoặc 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

Bảo vệ DNS Rebinding

Theo mặc định, bảo vệ DNS rebinding bị tắt để tương thích với proxy, cổng và dịch vụ Kubernetes. Để bật, sử dụng --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

Nếu bạn gặp lỗi 421 Invalid Host Header, hãy tắt bảo vệ (mặc định) hoặc thêm máy chủ của bạn vào danh sách được phép.

Bảo mật

Người dùng cơ sở dữ liệu chỉ đọc (Khuyến nghị)

Tạo người dùng chỉ đọc trong GreptimeDB bằng static user provider:

mcp_readonly:readonly=your_secure_password

Cổng bảo mật cấp ứng dụng

Tất cả truy vấn đi qua một cổng bảo mật:

• Chặn: DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT, REVOKE, EXEC, LOAD, COPY
• Chặn: Các nỗ lực vượt qua mã hóa (hex, UNHEX, CHAR)
• Cho phép: SELECT, SHOW, DESCRIBE, TQL, EXPLAIN, UNION

Chế độ ghi (Tắt theo mặc định)

Máy chủ chỉ đọc theo mặc định. Đối với phát triển cục bộ hoặc kiểm thử, bạn có thể cho phép SQL ghi/hủy diệt (DDL/DML như CREATE, DROP, ALTER, INSERT, UPDATE, DELETE) thông qua công cụ execute_sql bằng cách bật chế độ ghi:

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

Khi được bật, cổng bảo mật bị bỏ qua cho execute_sql, và máy chủ ghi nhật ký cảnh báo khi khởi động.

⚠️ Nguy hiểm: Điều này cho phép trợ lý AI chạy các câu lệnh hủy diệt chống lại cơ sở dữ liệu của bạn. Không bao giờ bật nó với dữ liệu sản xuất. Kết hợp với người dùng cơ sở dữ liệu chỉ đọc nếu bạn chỉ cần quyền truy cập đọc.

Che giấu dữ liệu

Các cột nhạy cảm tự động được che giấu (******) dựa trên các mẫu tên cột:

• Xác thực: password, secret, token, api_key, credential
• Tài chính: credit_card, cvv, bank_account
• Cá nhân: ssn, id_card, passport

Cấu hình với --mask-patterns phone,email để thêm các mẫu tùy chỉnh.

Ghi nhật ký kiểm toán

Tất cả các lệnh gọi công cụ được ghi nhật ký:

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

Tắt với --audit-enabled false.

Phát triển

# 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

Giấy phép

Giấy phép MIT - xem LICENSE.md.

Ghi nhận

Lấy cảm hứng từ:

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