GreptimeDB MCP Server

공식

AI 어시스턴트가 GreptimeDB의 데이터를 안전하고 구조화된 방식으로 탐색하고 분석할 수 있도록 지원합니다.

문서

greptimedb-mcp-server

GreptimeDB를 위한 모델 컨텍스트 프로토콜(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 구문을 사용한 시간 윈도우 집계 쿼리 실행
`describe_table`	테이블 프로필 검사: 스키마, 시맨틱 메타데이터, 최신 샘플 행, 쿼리 가이드
`explain_query`	SQL 또는 TQL 쿼리 실행 계획 분석 (런타임 통계를 보려면 `analyze=true`; 파티션별 스캔 메트릭 및 인덱스 정리 카운터를 보려면 `analyze=true`와 함께 `verbose=true` 추가)
`health_check`	데이터베이스 연결 상태 및 서버 버전 확인

파이프라인 관리

도구	설명
`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_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 인수

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 배포용. 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

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(예: CREATE, DROP, ALTER, INSERT, UPDATE, DELETE과 같은 DDL/DML)을 허용하려면 쓰기 모드를 활성화하세요:

# Environment variable
GREPTIMEDB_ALLOW_WRITE=true greptimedb-mcp-server

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

활성화되면 execute_sql에 대해 보안 게이트가 우회되며, 서버는 시작 시 경고를 기록합니다.

⚠️ 위험: 이는 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 참조.

감사의 말

다음에서 영감을 받았습니다: