GreptimeDB MCP Server

chính thức

Cung cấp cho trợ lý AI một cách an toàn và có cấu trúc để khám phá và phân tích dữ liệu trong GreptimeDB.

Tài liệu

greptimedb-mcp-server

Một máy chủ Giao thức Ngữ cảnh Mô hình (MCP) cho GreptimeDB — một cơ sở dữ liệu quan sát mã nguồn mở xử lý metrics, logs và traces trong cùng một engine.

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à các 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 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, thêm cấu hình này vào tệp 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 các tùy chọn định dạng (csv/json/markdown) và 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
`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` để có số liệu thống kê thời gian chạy; thêm `verbose=true` cùng với `analyze=true` để có số liệu quét từng 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ủ

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ý Bảng điều khiển

Công cụ	Mô tả
`list_dashboards`	Liệt kê tất cả định nghĩa bảng điều khiển Perses
`create_dashboard`	Tạo hoặc cập nhật định nghĩa bảng điều khiển Perses
`delete_dashboard`	Xóa một định nghĩa bảng điều khiển

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

Tài nguyên: Duyệt bảng qua các 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à sử dụng lời nhắc, xem docs/llm-instructions.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)

Tham số dòng lệnh

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

Dành cho triển khai container hóa hoặc Kubernetes. Yêu cầu mcp>=1.8.0:

# 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ệ chống DNS Rebinding

Theo mặc định, bảo vệ chống DNS rebinding bị vô hiệu hóa để tương thích với proxy, gateway và dịch vụ Kubernetes. Để kích hoạ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 cho 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 đều đi qua một cổng bảo mật có chức năng:

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 (Mặc định bị vô hiệu hóa)

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

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

Khi được kích hoạt, cổng bảo mật bị bỏ qua đối với execute_sql, và máy chủ ghi lại 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 hoại đối với cơ sở dữ liệu của bạn. Không bao giờ kích hoạt đối 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 dữ liệu

Các cột nhạy cảm được tự động che (******) 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ần gọi công cụ đều được ghi lại:

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

Vô hiệu hóa 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.

Lời cảm ơn

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