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의 경우, config에 다음을 추가하세요(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, 즉 1MiB)로 제한됩니다. 예산을 초과하는 쿼리 결과는 더 적은 행을 반환하고 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이 필요합니다. 시작 시 서버는 두 뷰가 존재하고, 읽는 열을 가지며, 연결된 계정이 읽을 수 있는지 확인합니다. 그렇지 않은 경우 도구가 제공되지 않고 이유가 기록됩니다. 시간 창은 필수이며 반개방형으로, observed_at에 걸친 [start_time, end_time)이며, 행은 해당 창의 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