GreptimeDB

官方

为AI助手提供安全且结构化的方式来探索和分析GreptimeDB中的数据。

GitHub

试用此 MCP赞助

你可以用 GreptimeDB MCP 做什么？

运行 SQL 查询 — 通过 execute_sql 请求指标、日志或追踪，支持 CSV、JSON 或 Markdown 输出及行数限制。
分析时间序列数据 — 使用 execute_tql 进行 PromQL 兼容查询，或使用 query_range 进行时间窗口聚合。
探索表结构 — 通过 describe_table 获取列类型、示例行及查询指导。
优化查询性能 — 使用 explain_query 请求执行计划，可选添加运行时统计或按分区扫描指标。
管理管道 — 使用 YAML 配置创建、测试、列出或删除数据处理管道。
处理仪表盘 — 列出、创建、更新或删除 Perses 仪表盘定义。

文档

greptimedb-mcp-server

一个用于 GreptimeDB 的模型上下文协议（MCP）服务器——GreptimeDB 是一个开源的可观测性数据库，可在同一引擎中处理指标、日志和追踪数据。

使 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`	执行 SQL 查询，支持格式（csv/json/markdown）和限制选项
`execute_tql`	执行 TQL（兼容 PromQL）查询以进行时间序列分析
`query_range`	使用 RANGE/ALIGN 语法执行时间窗口聚合查询
`search_table_semantics`	按可观测性概念查找表，按匹配术语排序；搜索表名、语义选项和实体声明
`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；在更早版本上，它会被报告为缺失列，而不是空声明集。

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`	删除仪表盘定义

资源与提示

资源：通过 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 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)

命令行参数

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
阻止：编码绕过尝试（十六进制、UNHEX、CHAR）
允许：SELECT、SHOW、DESCRIBE、TQL、EXPLAIN、UNION

写入模式（默认禁用）

服务器默认为只读。对于本地开发或测试，你可以通过启用写入模式来允许通过 execute_sql 工具执行写入/破坏性 SQL（DDL/DML，如 CREATE、DROP、ALTER、INSERT、UPDATE、DELETE）：

# 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。

致谢

灵感来源于：